From 1c47a39191b7b73929d13c2b7e94c26a098f184c Mon Sep 17 00:00:00 2001
From: Dimitrios <dimit.giannopoulos@upnet.gr>
Date: Sat, 6 Jul 2024 10:45:19 +0000
Subject: [PATCH] Deployed 467173f to develop in public with MkDocs 1.6.0 and
mike 2.1.2
---
.../develop/naas/lcm_rules_intro/index.html | 20 +-
public/develop/search/search_index.json | 2 +-
.../lcmrules/examples/index.html | 211 +++++++++++++++++-
.../lcmrules/images/lcm/lcmfig15.png | Bin 0 -> 292068 bytes
.../service_design/lcmrules/intro/index.html | 9 +-
.../lcmrules/specification/index.html | 78 ++++++-
6 files changed, 304 insertions(+), 16 deletions(-)
create mode 100644 public/develop/service_design/lcmrules/images/lcm/lcmfig15.png
diff --git a/public/develop/naas/lcm_rules_intro/index.html b/public/develop/naas/lcm_rules_intro/index.html
index 15bcfbda..f04258df 100644
--- a/public/develop/naas/lcm_rules_intro/index.html
+++ b/public/develop/naas/lcm_rules_intro/index.html
@@ -1182,6 +1182,15 @@
</span>
</a>
+</li>
+
+ <li class="md-nav__item">
+ <a href="#how-is-it-possible-to-intervene-in-the-workflow-process-and-affect-it" class="md-nav__link">
+ <span class="md-ellipsis">
+ How is it possible to intervene in the workflow process and affect it?
+ </span>
+ </a>
+
</li>
<li class="md-nav__item">
@@ -2715,6 +2724,15 @@
</span>
</a>
+</li>
+
+ <li class="md-nav__item">
+ <a href="#how-is-it-possible-to-intervene-in-the-workflow-process-and-affect-it" class="md-nav__link">
+ <span class="md-ellipsis">
+ How is it possible to intervene in the workflow process and affect it?
+ </span>
+ </a>
+
</li>
<li class="md-nav__item">
@@ -2757,7 +2775,7 @@
<p>So in the system there are already predefined recipes, which in each process-step of the workflow some piece of code is executed. </p>
<p>How is it possible to intervene in the workflow process and inject some user defined actions? The next image illustrates the idea</p>
<p><a href="../lcm/img02.png"><img alt="lcm" src="../lcm/img02.png" /></a></p>
-<p>## How is it possible to intervene in the workflow process and affect it?</p>
+<h2 id="how-is-it-possible-to-intervene-in-the-workflow-process-and-affect-it">How is it possible to intervene in the workflow process and affect it?</h2>
<p>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:</p>
<ul>
<li>PRE_PROVISION</li>
diff --git a/public/develop/search/search_index.json b/public/develop/search/search_index.json
index 0c9c4242..ba1307f2 100644
--- a/public/develop/search/search_index.json
+++ b/public/develop/search/search_index.json
@@ -1 +1 @@
-{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Introduction","text":"<p>version: 2024Q2 - SNAPSHOT</p> <p>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.</p>"},{"location":"#usage","title":"Usage","text":"<p>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. </p> <p></p> <p>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. </p>"},{"location":"#an-end-to-end-e2e-service-orchestration-framework","title":"An end-to-end (E2E) service orchestration framework","text":"<p>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:</p> <ul> <li>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.</li> <li>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.</li> <li>Service Design and Creation tharough service templates based on predefined models for creating services.</li> <li>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.</li> <li>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</li> <li>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.</li> <li>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.</li> <li>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.</li> </ul>"},{"location":"#an-e2e-service-orchestration-workflow","title":"An E2E service orchestration workflow","text":"<p>In general an E2E service orchestration workflow includes the following phases:</p> <ul> <li>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.</li> <li>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.</li> <li>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</li> <li>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.</li> <li>Lifecycle Management: The orchestration framework handles updates, scaling, and any necessary modifications throughout the service lifecycle.</li> <li>At the end of the service period, resources are decommissioned and reclaimed.</li> </ul>"},{"location":"#openslice-for-service-providers","title":"OpenSlice for Service Providers","text":"<p>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.</p> <p>There are various portals offering UI friendly access to users acting as Service Providers:</p> <ul> <li>The Services portal allows Service Providers to design and expose services.</li> <li>The Resource portal allows users to access resource specifications and running resources in resource inventory.</li> <li>The NFV portal allows users to manage NFV artifacts and onboard them to a target MANO/NFV Orchestrator.</li> <li>The Testing portal allows Service Providers to manage test artifacts</li> <li>The Products portal allows Service Providers to expose services as products</li> </ul>"},{"location":"#openslice-for-service-consumers","title":"OpenSlice for Service Consumers","text":"<p>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:</p> <ul> <li>The Services portal allows Service Consumers to select and order predefined services.</li> <li>The Resource portal allows users to access running resources in resource inventory.</li> <li>The NFV portal allows users to self-manage NFV artifacts and onboard them to a target MANO/NFV Orchestrator.</li> <li>The Testing portal allows Service Consumers to manage test artifacts</li> <li>The Products portal allows Service Consumers to expose services as products</li> </ul> <p>3rd party applications can use OpenSlice through TMForum Open APIs.</p>"},{"location":"#live-demo","title":"Live Demo","text":"<p>Check a live demo of OpenSlice in the following pages:</p> <p>(username=admin, password=openslice or username=admin, password=changeme)</p> <ul> <li>OpenSlice demo: http://portal.openslice.io/</li> <li>OpenSlice Service Catalogs and ordering: http://portal.openslice.io/services/</li> <li>OpenSlice NFV Services onboarding: http://portal.openslice.io/nfvportal </li> </ul>"},{"location":"#probe-further","title":"Probe further","text":"<ul> <li>Installing OpenSlice. See the Deployment of OpenSlice</li> <li>Learn more on [how OpenSlice supports Network as a Service(NaaS)](./naas/introduction</li> <li>Who is implementing OpenSlice? See OSL ETSI SDG</li> <li>How OpenSlice works? See the Architecture of OpenSlice</li> </ul>"},{"location":"OpenSlice_deployment_examples/","title":"OpenSlice deployment examples","text":"<p>Here are some examples from past and current efforts that use OpenSlice in various cases.</p>"},{"location":"OpenSlice_deployment_examples/#5ginfire-eu-project2018","title":"5GinFIRE EU project(2018)","text":"<ul> <li>MultiVIM approach</li> <li>9 Testbeds</li> <li>Automotive, Smart City, eHeath, \u000bPPDR, Media, SDR, Cloud</li> <li>22 Experiment proposals from Verticals</li> <li>100+ Users</li> <li>VxF catalog: </li> <li>150+ ONBOARDED VxFs</li> <li>OSM TWO, FOUR, FIVE</li> <li>50+ are public to be reused</li> <li>NSD catalog: </li> <li>90+ ONBOARDED NSDs</li> <li>30+ are public to be reused</li> <li>500+ Deployment requests \u000b(orchestrations) performed</li> </ul> <p>[</p>"},{"location":"OpenSlice_deployment_examples/#5g-vinni-eu-project-2020","title":"5G-VINNI EU project (2020)","text":"<ul> <li>Multi-vendor challenge \u2013 Commercial and opensource</li> <li>5G services on multiple sites</li> <li>Introduction of TMFORUM models and APIs </li> </ul> <p>[</p>"},{"location":"OpenSlice_deployment_examples/#5gasp-eu-project-2021-2024","title":"5GASP EU project (2021-2024)","text":"<ul> <li>Support a multi-site CI/CD testing automated DevOps cycle for network Applications</li> <li>Multiple NFVOs</li> <li>Introducing Service Test models</li> <li>Introducing the Product models for a network application marketplace</li> </ul> <p>[</p>"},{"location":"OpenSlice_deployment_examples/#fidal-eu-project-2023-","title":"FIDAL EU project (2023-)","text":"<ul> <li>Support multi-site automated testing</li> <li>Multiple testbeds/ different APIs</li> </ul> <p>[</p>"},{"location":"OpenSlice_deployment_examples/#across-eu-project-2023-","title":"ACROSS EU project (2023-)","text":"<ul> <li>Used as a cross-domain orchestrator</li> <li>Support the multi-domain orchestrator</li> <li>Support Zero-touch provisioning concepts</li> </ul> <p>[</p>"},{"location":"OpenSlice_deployment_examples/#incode-eu-project-2023-","title":"INCODE EU project (2023-)","text":"<ul> <li>Support the provisioning of end-to-end domain services</li> </ul> <p>[</p>"},{"location":"OpenSlice_deployment_examples/#imagineb5g-eu-project-2023-","title":"IMAGINEB5G EU project (2023-)","text":"<ul> <li>Support the provisioning of end-to-end domain services</li> </ul>"},{"location":"OpenSlice_deployment_examples/#etsi-zsm-poc-2","title":"ETSI ZSM PoC #2","text":"<ul> <li>Automated Network Slice Scaling in Multi-Site Environments</li> </ul> <p>[</p>"},{"location":"alarms_actions/","title":"Alarms","text":"<p>In Openslice parts of TMF642 Alarm Management API are currently implemented. Alarms can be managed through the TMF API endpoint as well as the UI.</p>"},{"location":"alarms_actions/#alarms-and-actions","title":"Alarms and Actions","text":"<p>Note: Actions is an experimental feature. We expect to have a more mature solution in future. The component in the architecture is the Openslcie Assurance Services</p> <p>Alarms can be automatically resolved by specific actions. Today only the following actions are offered.</p> <ul> <li>execDay2</li> <li>scaleServiceEqually</li> </ul>"},{"location":"alarms_actions/#execday2","title":"execDay2","text":"<p>Usually used to perform a Day2 configuration (towards OSM). To use it, Create a New Action Specification Name=execDay2 as following</p> <p></p> <p>Now make a Service Order for your service. In this example \u03c2\u03b5 used a cirros NSD</p> <p>Create a New Action Rule for the running services as the following example:</p> <p></p> <p>The scope is the running cirros service. </p> <p>Params should be paramname=value;paramname2=value2;paramname3=value3 (must exist in the VNF otherwise OSM will raise an error).</p> <p>In this case should be filename=test.txt</p> <p>Primitive=touch</p> <p>ServiceId = select the service which will accept the Day2. In this case is the same</p> <p>To test it:</p> <p>Go to the Service Inventory and select the active Service.</p> <p>Note the UUID of the service (e.g. c4e7990a-e174-4cd2-9133-b10e56721e08 copy from address bar), DeploymentRequestID and NSDID from characteristics</p> <p>You can either use the UUID of the service or the DeploymentRequestID and POST to the Alarms endpoint ( /tmf-api/alarmManagement/v4/alarm)</p> <p>If the DeploymentRequestID is used then POST:</p> <pre><code>\n{\n \"alarmRaisedTime\": \"2021-06-29T12:30:24.675Z\",\n \"alarmReportingTime\": \"2021-06-29T12:30:54.675Z\",\n \"state\": \"raised\",\n \"alarmType\": \"qualityOfServiceAlarm\",\n \"probableCause\": \"thresholdCrossed\",\n \"ackState\": \"unacknowledged\",\n \"perceivedSeverity\": \"major\",\n \"sourceSystemId\": \"mano-client-service\",\n \"alarmDetails\": \"NSID=3;DeploymentRequestID=1\",\n \"specificProblem\": \"myalram raised\"\n}\n\n</code></pre> <p>If the UUID is used then POST:</p> <pre><code>\n{\n \"alarmRaisedTime\": \"2021-06-29T12:30:24.675Z\",\n \"alarmReportingTime\": \"2021-06-29T12:30:54.675Z\",\n \"state\": \"raised\",\n \"alarmType\": \"qualityOfServiceAlarm\",\n \"probableCause\": \"thresholdCrossed\",\n \"ackState\": \"unacknowledged\",\n \"perceivedSeverity\": \"major\",\n \"sourceSystemId\": \"mano-client-service\",\n \"alarmDetails\": \"analarm\",\n \"specificProblem\": \"myalram raised\",\n \"affectedService\": [\n {\n \"id\": \"c4e7990a-e174-4cd2-9133-b10e56721e08\"\n }\n ]\n\n}\n\n</code></pre> <p>The Alarm to be created must have the affected Service ID equal to the running service from the scope (the cirros_ns)</p> <p>Go to service inventory you will see the notes and also the service characteristics for any EXEC_ACTION updates</p> <p>You can also adjust the alarm conditions. They must match true so the alarm to be acknowledged So if another external service raises an Alarm (with POST) for the running service, a Day2 will be performed on another Service</p>"},{"location":"alarms_actions/#scaleserviceequally","title":"scaleServiceEqually","text":"<p>This action is used from getting a scaling event from OSM. Please see the next demo for details on how it works</p>"},{"location":"alarms_actions/#prototype-demo","title":"Prototype demo","text":"<p>You can watch how we used the prototype on the following ETSI ZMS PoC #2</p> <ul> <li>ETSI ZMS PoC #2: https://www.etsi.org/events/1905-webinar-zsm-poc-2-showcase-automated-network-slice-scaling-in-multi-site-environments/</li> </ul>"},{"location":"config_intro/","title":"Configuring and managing OpenSlice","text":""},{"location":"config_intro/#intended-audience-openslice-administrators","title":"Intended Audience: OpenSlice administrators","text":"<p>This section provides information on how to configure and manage different aspect of OpenSlice while in operation. For example:</p> <ul> <li>Manage user roles and access in Keycloak</li> <li>Configure/Manage NFVOs</li> <li>Advanced configuration scenarios</li> </ul>"},{"location":"deployment/","title":"OpenSlice Deployment","text":"<p>This section is meant to guide the user through the installation of OpenSlice. </p>"},{"location":"deployment/#intended-audience-openslice-administrators","title":"Intended Audience: OpenSlice administrators","text":"<p>Following, you may thorough guides depending on the installation type of your choice:</p> <ul> <li>Installing via Docker Compose guide</li> <li>Installing via Kubernetes guide</li> </ul>"},{"location":"deploymentCompose/","title":"OpenSlice Deployment Guide with Docker Compose","text":""},{"location":"deploymentCompose/#intended-audience-openslice-administrators","title":"Intended Audience: OpenSlice administrators","text":""},{"location":"deploymentCompose/#requirements","title":"Requirements","text":""},{"location":"deploymentCompose/#hardware-requirements","title":"Hardware requirements:","text":"Minimum Hardware Requirements Recomended Hardware Requirements 4 CPU cores 8 CPU cores 8 GB RAM 16 GB RAM 30 GB storage 50 GB storage"},{"location":"deploymentCompose/#software-requirements","title":"Software Requirements:","text":"<ul> <li>Docker: A running environment for Docker Compose services</li> </ul>"},{"location":"deploymentCompose/#preparing-the-environment","title":"Preparing the environment","text":""},{"location":"deploymentCompose/#1-backup-your-previous-database-if-necessary","title":"1. Backup your previous database if necessary:","text":"<pre><code>sudo docker exec amysql /usr/bin/mysqldump -u root --password=letmein ostmfdb > backup_ostmfdb.sql\n</code></pre>"},{"location":"deploymentCompose/#2-install-docker","title":"2. Install docker","text":"<p>Since July 2023 Docker Compose V1 stopped receiving updates. OpenSlice fully reverted to Compose V2, which is integrated in the Docker installation.</p>"},{"location":"deploymentCompose/#3-configure-containers-to-properly-resolve-the-dns-of-your-domain-optional","title":"3. Configure containers to properly resolve the DNS of your domain (optional)","text":"<pre><code>sudo nano /etc/docker/daemon.json\n</code></pre> <p>and add:</p> <pre><code>{ \n \"dns\": [\"8.8.8.8\", \"8.8.4.4\"]\n}\n</code></pre> <p>After editing daemon.json restart docker daemon for the changes to take place</p> <pre><code>sudo systemctl restart docker\n</code></pre>"},{"location":"deploymentCompose/#downloading-the-project","title":"Downloading the project","text":""},{"location":"deploymentCompose/#1-create-a-new-folder-to-download-the-project","title":"1. Create a new folder to download the project","text":"<pre><code>mkdir openslice\n</code></pre> <pre><code>cd openslice\n</code></pre>"},{"location":"deploymentCompose/#2-download-the-deployment-script","title":"2. Download the deployment script","text":"<p>Download the deployment / environment preparation script</p> <pre><code>wget https://labs.etsi.org/rep/osl/code/org.etsi.osl.main/-/raw/develop/compose/deploy.sh\n</code></pre> <p>Make it executable</p> <pre><code>sudo chmod +x deploy.sh\n</code></pre>"},{"location":"deploymentCompose/#3-run-the-deployment-script","title":"3. Run the deployment script","text":"<p>OpenSlice is a multi repo project. This script selects the same branch for all repositories of the project to pull from.</p> <p>After that it builds the respective jar files locally and installs all the npm packages needed for the UI.</p> <p>If you run the script without selecting a branch the the main branch is going to be selected.</p> <p>We recommend:</p> <ul> <li>main branch for the most stable experience and</li> <li>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)</li> </ul> <pre><code>sudo ./deploy.sh develop #[or replace main with other branch name]\n</code></pre> <p>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.</p>"},{"location":"deploymentCompose/#configure-docker-compose-services","title":"Configure Docker Compose services","text":""},{"location":"deploymentCompose/#1-create-configuration-specific-docker-compose-file-from-the-template","title":"1. Create configuration specific Docker Compose file from the template","text":"<pre><code>cd org.etsi.osl.main/compose/\n</code></pre> <pre><code>sudo cp docker-compose.yaml.configure docker-compose.yaml\n</code></pre>"},{"location":"deploymentCompose/#2-configure-mysql-portal-container-optional","title":"2. Configure mysql-portal container (optional)","text":"<ol> <li>In folder <code>org.etsi.osl.main/compose/mysql-init</code> edit the file <code>01-databases.sql</code>.</li> <li>In the <code>org.etsi.osl.main/compose/docker-compose.yaml</code> edit the credentials of the users that services use to connect to the databases, if you wish.<ul> <li>portaluser (default is 12345) and</li> <li>keycloak (default is password)</li> </ul> </li> </ol>"},{"location":"deploymentCompose/#3-configure-keycloak-container-optional","title":"3. Configure keycloak container (optional)","text":"<ol> <li> <p>If you made changes to keycloak's mysql credentials:</p> <p>In folder <code>org.etsi.osl.main/compose/</code> edit the file <code>docker-compose.yaml</code>.</p> </li> </ol> <pre><code>DB_DATABASE: keycloak\nDB_USER: keycloak\nDB_PASSWORD: password\n</code></pre> <ol> <li> <p>If you want to change the keycloak admin password:</p> <p>In folder <code>org.etsi.osl.main/compose/</code> edit the file <code>docker-compose.yaml</code></p> </li> </ol> <pre><code>KEYCLOAK_PASSWORD: Pa55w0rd\n</code></pre>"},{"location":"deploymentCompose/#4-configure-bugzilla-container-optional","title":"4. Configure bugzilla container (optional)","text":"<p>If you want to utilise the Bugzilla connector:</p> <p>In folder <code>org.etsi.osl.main/compose/</code> edit the file <code>docker-compose.yaml</code></p> <pre><code>SPRING_APPLICATION_JSON: '{\n \"spring.activemq.brokerUrl\": \"tcp://anartemis:61616?jms.watchTopicAdvisories=false\",\n \"spring.activemq.user\": \"artemis\",\n \"spring.activemq.password\": \"artemis\",\n \"bugzillaurl\":\"\",\n \"bugzillakey\":\"\",\n \"main_operations_product\":\"\"\n}'\n</code></pre> <p>And add the provided Bugzilla installation information:</p> <pre><code>\"bugzillaurl\":\"bugzillaurl.xx:443/bugzilla/\",\n\"bugzillakey\":\"exampleKeyeqNNwxBlgxZgMEIne0Oeq0Bz\",\n\"main_operations_product\":\"Main Site Operations\" // this is the default product to issue tickets\n</code></pre> <p>Bugzilla should have the following components under the specified product: </p> <ul> <li>NSD Deployment Request: Component used to schedule deployment req </li> <li>Onboarding: Issues related to VNF/NSD Onboarding </li> <li>Operations Support: Default component for operations support </li> <li>Validation: Use to track validation processes of VNFs and NSDs </li> <li>VPN Credentials/Access: Used for requesting VPN Credentials/Access </li> </ul> <p>Also in the 'Main Site Operations' product, a version named 'unspecified' must be created.</p>"},{"location":"deploymentCompose/#5-configure-osportalapi-container-nfv-services-conditional","title":"5. Configure osportalapi container (NFV services) (conditional)","text":"<p>Change the respective fields: </p> <ul> <li>If you made changes to mysql and keycloak credentials.</li> <li>If you want to change logging level (TRACE / DEBUG / INFO / WARN / ERROR).</li> </ul> <p>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.</p> <p>In folder <code>org.etsi.osl.main/compose/</code> edit the file <code>docker-compose.yaml</code></p> <pre><code>SPRING_APPLICATION_JSON: '{\n \"spring.datasource.username\":\"root\",\n \"spring.datasource.password\":\"letmein\",\n \"spring-addons.issuers[0].uri\": \"http://keycloak:8080/auth/realms/openslice\",\n \"spring.security.oauth2.resourceserver.jwt.issuer-uri\": \"http://keycloak:8080/auth/realms/openslice\",\n \"springdoc.oAuthFlow.authorizationUrl\": \"http://keycloak:8080/auth/realms/openslice/protocol/openid-connect/auth\",\n \"springdoc.oAuthFlow.tokenUrl\": \"http://keycloak:8080/auth/realms/openslice/protocol/openid-connect/token\", \n \"spring.portal.main.domain\": \"http://localhost\",\n \"logging.level.org.springframework\" : \"INFO\"\n}'\n</code></pre>"},{"location":"deploymentCompose/#6-osscapi-container-tmf-api-service-conditional","title":"6. osscapi container (TMF API service) (conditional)","text":"<p>Change the respective fields: </p> <ul> <li>If you made changes to mysql and keycloak credentials.</li> <li>If you want to change logging level (TRACE / DEBUG / INFO / WARN / ERROR).</li> </ul> <p>If you are using a non-local domain, replace everywhere the http://keycloak:8080 with the respective {{protocol://domain.name}}.</p> <p>In folder <code>org.etsi.osl.main/compose/</code> edit the file <code>docker-compose.yaml</code></p> <pre><code>SPRING_APPLICATION_JSON: '{\n \"spring.datasource.username\":\"root\",\n \"spring.datasource.password\":\"letmein\",\n \"spring-addons.issuers[0].uri\": \"http://keycloak:8080/auth/realms/openslice\",\n \"spring.security.oauth2.resourceserver.jwt.issuer-uri\": \"http://keycloak:8080/auth/realms/openslice\",\n \"springdoc.oAuthFlow.authorizationUrl\": \"http://keycloak:8080/auth/realms/openslice/protocol/openid-connect/auth\",\n \"springdoc.oAuthFlow.tokenUrl\": \"http://keycloak:8080/auth/realms/openslice/protocol/openid-connect/token\", \n \"logging.level.org.springframework\" : \"INFO\"\n}'\n</code></pre>"},{"location":"deploymentCompose/#configure-nginx","title":"Configure nginx","text":"<p>In folder <code>org.etsi.osl.main/compose/nginx</code> create a configuration specific <code>nginx.conf</code> file.</p> <pre><code>cd org.etsi.osl.main/compose/nginx/\n</code></pre> <pre><code>sudo cp nginx.conf.default nginx.conf\n</code></pre> <p>If needed, in the nginx.conf file, edit the server_name for an non-local deployment.</p>"},{"location":"deploymentCompose/#configure-web-ui","title":"Configure Web UI","text":"<p>In folder <code>org.etsi.osl.portal.web/src/js/</code> create a configuration specific <code>config.js</code> file.</p> <pre><code>cd org.etsi.osl.portal.web/src/js\n</code></pre> <pre><code>sudo cp config.js.default config.js\n</code></pre> <p>Edit the <code>config.js</code> file with the information of your domain. <code>ROOTURL</code> will automatically extract the the Origin (Protocol://Domain:Port) of the deployment, but you must change <code>APIURL</code> property, if you are not aiming for a localhost installation, e.g. \"https://portal.openslice.io\".</p> <p>Example file:</p> <pre><code>{ \n BUGZILLA: \"ROOTURL/bugzilla/\",\n STATUS: \"ROOTURL/status/\",\n APIURL: \"http://localhost\",\n WEBURL: \"ROOTURL/nfvportal\",\n APIOAUTHURL: \"ROOTURL/auth/realms/openslice\",\n APITMFURL: \"ROOTURL/tmf-api/serviceCatalogManagement/v4\"\n}\n</code></pre>"},{"location":"deploymentCompose/#configure-tmf-web-ui","title":"Configure TMF Web UI","text":"<p>In the folder <code>org.etsi.osl.tmf.web/src/assets/config</code> there are 3 files available for configuration:</p> <ul> <li>config.prod.json (Basic information + API configuration)</li> <li>theming.scss (CSS color palette theming)</li> <li>config.theming.json (HTML configuration - Logo, Favicon, Footer)</li> </ul> <p>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 <code>org.etsi.osl.tmf.web/src/assets/config</code> directory as a copy of the default ones from the remote repository.</p> <p>Ensure that you check the <code>config.prod.json</code> and <code>theming.scss</code> files and readjust to your deployment if needed.</p> <pre><code># Starting from the root project directory\ncd org.etsi.osl.tmf.web/src/assets/config\n</code></pre> <p>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.</p> <p>Example file:</p> <pre><code>{ \n \"TITLE\": \"OpenSlice by ETSI\",\n \"PORTALVERSION\":\"2024Q2\",\n \"WIKI\": \"https://osl.etsi.org/documentation\",\n \"BUGZILLA\": \"{BASEURL}/bugzilla/\",\n \"STATUS\": \"{BASEURL}/status/\",\n \"WEBURL\": \"{BASEURL}\",\n \"PORTAL_REPO_APIURL\": \"{BASEURL}/osapi\",\n \"ASSURANCE_SERVICE_MGMT_APIURL\": \"{BASEURL}/oas-api\",\n \"APITMFURL\": \"{BASEURL}/tmf-api\",\n \"OAUTH_CONFIG\" : {\n \"issuer\": \"{BASEURL}/auth/realms/openslice\",\n \"loginUrl\": \"{BASEURL}/auth/realms/openslice/protocol/openid-connect/auth\",\n \"tokenEndpoint\": \"{BASEURL}/auth/realms/openslice/protocol/openid-connect/token\",\n \"userinfoEndpoint\": \"{BASEURL}/auth/realms/openslice/protocol/openid-connect/userinfo\",\n \"redirectUri\": \"{BASEURL}/redirect\",\n \"logoutUrl\": \"{BASEURL}/auth/realms/openslice/protocol/openid-connect/logout\", \n \"postLogoutRedirectUri\": \"{BASEURL}\",\n\n \"responseType\": \"code\",\n \"oidc\": false,\n \"clientId\": \"osapiWebClientId\",\n \"dummyClientSecret\": \"secret\",\n\n \"requireHttps\": false,\n \"useHttpBasicAuth\": true,\n \"clearHashAfterLogin\": false,\n\n \"showDebugInformation\": true\n }\n}\n</code></pre> <p>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\".</p> <p>If further customization, apart from the default provided, is needed for branding (Logo, Footer) then <code>config.theming.json</code> needs to be created in io.openslice.tmf.web/src/assets/config directory, as follows:</p> <pre><code># Starting from the root project directory\ncd org.etsi.osl.tmf.web/src/assets/config\n</code></pre> <pre><code>sudo cp config.theming.default.json config.theming.json\n</code></pre> <p>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 <code>org.etsi.osl.tmf.web/dist/io-openslice-portal-web/assets/config</code> directory. Although, it is mandatory to also apply these changes to the <code>org.etsi.osl.tmf.web/src/assets/config</code> for persistancy, as after any future rebuild of OpenSlice the <code>/dist</code> 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 <code>org.etsi.osl.tmf.web/src/assets/config</code> and rebuild the application.</p>"},{"location":"deploymentCompose/#deploy-openslice-via-docker-compose","title":"Deploy OpenSlice via Docker Compose","text":"<p>After configuring the services, and editing the docker compose file accordingly, the docker compose instantiation command can be performed.</p> <pre><code># Starting from the root project directory\ncd org.etsi.osl.main/compose/\n</code></pre> <pre><code>sudo docker compose --profile prod down;sudo docker compose --profile prod up -d --build\n</code></pre> <p>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.</p>"},{"location":"deploymentCompose/#validating-deployments-and-container-monitoring","title":"Validating deployments and container monitoring","text":"<p>You can monitor containers' status with portainer at port 9000 (http://your-ip:9000).</p> <p>Initially, you may monitor the local machine at portainer.</p> <p>Please check that all containers are in running state.</p>"},{"location":"deploymentCompose/#post-installation-steps","title":"Post installation steps","text":"<p>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.</p>"},{"location":"deploymentCompose/#configure-keycloak-server","title":"Configure Keycloak server","text":"<p>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. </p> <ul> <li> <p>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) </p> </li> <li> <p>Navigate to Administration Console </p> </li> <li> <p>Login with the credentials from section Configure keycloak container. Default values are:</p> <ul> <li>user: admin and </li> <li>password: Pa55w0rd</li> </ul> </li> </ul> <p>if you are running in HTTP you will get a message: HTTPS required.</p> <p>To resolve this issue when running in HTTP: </p> <ul> <li>Select the master realm from top left corner</li> <li>Go to login Tab and select \"Require SSL\": None</li> <li>Repeat for realm Openslice</li> </ul> <p>If you are running in HTTPS, then \"Require SSL\" can be left unchanged to external requests.</p>"},{"location":"deploymentCompose/#1-configure-redirects","title":"1. Configure redirects","text":"<p>Navigate to realm Openslice > Clients > osapiWebClientId and change the Root URL to your domain. </p> <p>Also, insert your domain, e.g. http://example.org/*, at:</p> <ul> <li>Valid Redirect URIs</li> <li>Web Origins</li> </ul>"},{"location":"deploymentCompose/#2-configure-email","title":"2. Configure email","text":"<p>Keycloak allows new users to register. Subsequently, this will also allow new users to register to the OpenSlice portal.</p> <p>Navigate to realm Openslice > Realm Settings > Login Tab > check User registration, Verify email, Forgot password etc.</p> <p>Finally, enter the details of the mail server at the Email Tab.</p> <p>Email configuration is optional for test runs, but if not provided the above functionalities (e.g. external user registration) will not be possible.</p>"},{"location":"deploymentCompose/#3-add-an-openslice-admin-user","title":"3. Add an OpenSlice admin user","text":"<p>This step is mandatory so as to access the OpenSlice Web UI. To add an OpenSlice admin user you must:</p> <ul> <li>Navigate to realm Openslice > Users > Add user</li> <li>Set a password</li> <li>Upon creation, navigate to Role Mappings and add ADMIN to Assigned Roles list</li> </ul> <p>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.</p>"},{"location":"deploymentCompose/#keycloak-at-localhost","title":"Keycloak at localhost","text":"<p>This is an important step if you run Keycloak on localhost!</p> <p>1 - Edit your Hosts File, adding the line below</p> <p><code>127.0.0.1 keycloak</code></p> <p>Hosts File Location:</p> <ul> <li> <p>In Linux/Unix, the file's location is at /etc/hosts </p> </li> <li> <p>In Windows, its location is at c:\\Windows\\System32\\Drivers\\etc\\hosts</p> </li> </ul> <p>2 - Replace http://localhost/auth/ with http://keycloak:8080/auth/ in your Keycloak config for AngularJS and Angular (see examples below).</p> <p>Explanation</p> <p>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.</p> <p>2.1 - For the Angular configuration (TMF portal UI), navigate to org.etsi.osl.tmf.web/src/assets/config and edit config.prod.json</p> <pre><code># Starting from the root project directory\ncd org.etsi.osl.tmf.web/src/assets/config\n</code></pre> <pre><code>nano config.prod.json\n</code></pre> <p>After editing, the displayed properties should look like the example below:</p> <pre><code>{ \n \"OAUTH_CONFIG\" : {\n \"issuer\": \"http://keycloak:8080/auth/realms/openslice\",\n \"loginUrl\": \"http://keycloak:8080/auth/realms/openslice/protocol/openid-connect/auth\",\n \"tokenEndpoint\": \"http://keycloak:8080/auth/realms/openslice/protocol/openid-connect/token\",\n \"userinfoEndpoint\": \"http://keycloak:8080/auth/realms/openslice/protocol/openid-connect/userinfo\",\n \"redirectUri\": \"{BASEURL}/redirect\",\n \"logoutUrl\": \"http://keycloak:8080/auth/realms/openslice/protocol/openid-connect/logout\", \n \"postLogoutRedirectUri\": \"{BASEURL}\",\n }\n}\n</code></pre> <p>Note the difference in changing {BASEURL} -> http://keycloak:8080</p> <p>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</p> <p>2.2 - For the AngularJS configuration (NVF portal UI), navigate to org.etsi.osl.portal.web/src/js and edit config.js</p> <pre><code># Starting from the root project directory\ncd org.etsi.osl.portal.web/src/js\n</code></pre> <pre><code>nano config.js\n</code></pre> <p>After editing, the displayed properties should look like the example below:</p> <pre><code>var appConfig = angular.module('portalwebapp.config',[]);\n\n\nappConfig.factory('APIEndPointService', function() {\n return { \n APIOAUTHURL: \"http://keycloak:8080/auth/realms/openslice\",\n };\n});\n</code></pre> <p>Note the difference in \"APIOAUTHURL\" property, changing ROOTURL -> http://keycloak:8080</p>"},{"location":"deploymentCompose/#nfv-orchestrator-configuration","title":"NFV Orchestrator Configuration","text":"<p>After successfully deploying and configuring OpenSlice, you may configure its environment (e.g. the NFVO) that will facilitate the deployment of NFV artifacts.</p> <p>See NFV Orchestrator Configuration.</p>"},{"location":"deploymentK8s/","title":"OpenSlice Deployment Guide with Kubernetes","text":""},{"location":"deploymentK8s/#intended-audience-openslice-administrators","title":"Intended Audience: OpenSlice administrators","text":"<p>This is WIP.</p> <p>Please refer to this guide.</p>"},{"location":"etsi_osl/","title":"The ETSi SDG OSL","text":"<p>OpenSlice is developed by the OSL ETSI Software Development Group see more info</p>"},{"location":"history/","title":"History","text":""},{"location":"history/#history","title":"History","text":"<ul> <li>The NFV portal part of OpenSlice was initially developed in H2020 European Research project 5GinFIRE by University of Patras, Greece</li> <li>OpenSlice core services, APIs was further developed and maintained in H2020 European project 5G-VINNI by University of Patras, Greece</li> <li>OpenSlice has been a part of OSM's OSS/BSS ecosystem</li> <li>OpenSlice is now an ETSI SDG Group since 2023</li> </ul>"},{"location":"history/#citation","title":"Citation","text":"<p>Please cite our ![paper] if you use OpenSlice in your research</p> <pre><code>\n@misc{tranoris2021openslice,\n title={Openslice: An opensource OSS for Delivering Network Slice as a Service}, \n author={Christos Tranoris},\n year={2021},\n eprint={2102.03290},\n archivePrefix={arXiv},\n primaryClass={cs.NI}\n}\n\n\n</code></pre>"},{"location":"nfvoconfig/","title":"NFV Orchestrator configuration","text":"<p>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.</p> <p>Configuration of your target(s) NFVOs/MANO services with Openslice is performed through the NFV portal.</p> <ol> <li> <p>Login to {{yourdomain}}/nfvportal/</p> </li> <li> <p>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.</p> </li> <li> <p>Navigate to Admin > Manage MANO providers > Add New MANO Provider and enter its details:</p> <ul> <li>Name and description of your choice. The selected name will supplement the NFV artifacts of this provider.</li> <li>One of the already defined MANO platforms</li> <li>API URL Endpoint, eg: https://10.10.10.10:9999 (This is the SOL005 NBI endpoint - Note the port 9999)</li> <li>Username, Password and Project of your OSM tenant.</li> </ul> </li> </ol> <p>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).</p> <p>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). </p> <p>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 <code>OSM_PRESENT</code>. If during this process, an artifact is deleted from the MANO, the respective status field will be updated to <code>OSM_MISSING</code>.</p>"},{"location":"portals_intro/","title":"OpenSlice Portals","text":"<p>Openslice comprises of a web landing page See Demo that navigates to the respective Portal:</p> <ul> <li>Services Portal See Demo</li> <li>NFV Portal See Demo</li> <li>Products Portal See Demo</li> <li>Testing Portal See Demo</li> <li>Resources Portal See Demo</li> </ul> <p>Following you may find the scope each portal focuses on and the main TMF APIs it supports.</p> <p>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.</p> <p>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</p> <p>More information can be found at NFV Services.</p> <p>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.</p> <p>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.</p> TMF620 TMF632 TMF633 TMF634 TMF638 TMF639 TMF640 TMF641 TMF642 TMF653 TMF685 Services Portal x x x x x x Products Portal x x Testing Portal x x Resources Portal x x x x <p>The NFV Portal uses a proprietary API</p>"},{"location":"role_keycloak_management/","title":"Role management in Keycloak","text":"<p>Some initial configuration of Keycloak happens at Installation/Deployment time. Here are some notes regarding user management</p>"},{"location":"role_keycloak_management/#intended-audience-openslice-administrators","title":"Intended Audience: OpenSlice administrators","text":"<p>There are cases that OpenSlice administrators need to configure Keycloak:</p> <ul> <li>Change user roles, e.g. make a Simple user a Service Designer</li> <li>Domain management</li> <li>User Password reset</li> </ul>"},{"location":"terminology/","title":"User Roles","text":"<ul> <li>User</li> <li>Service Designer</li> <li>OpenSlice administrator</li> </ul>"},{"location":"terminology/#terms","title":"Terms","text":"<ul> <li>Resource Facing Service Specification (RFSSpec): A Service that exposes a resource Specification as a Service.</li> <li>Customer Facing Service Specification (CFSSpec): Service exposed to users for Service Orders. Usually it exposes other CFSSpec(Service Bundle) or other RFSSpecs</li> <li>OpenSlice management cluster</li> <li>Service Specification: Detailed descriptions of services, including attributes, configurations, performance metrics, and SLAs.</li> <li>Service Catalog</li> <li>Service Categories</li> <li>Service Inventory</li> </ul>"},{"location":"under_construction/","title":"Under construction","text":"<p>under construction</p>"},{"location":"architecture/architecture/","title":"Architecture","text":"<p>Openslice offers the following main functionalities:</p> <ul> <li>Service Catalog Management: A CSP will have the ability to manage the Service Catalog Items, their attributes , organize in categories and decide what to make available to Customers</li> <li>Services Specifications: A CSP will be able to manage Service Specifications</li> <li>Service Catalog Exposure: A CSP will be able to expose catalog to customers and related parties</li> <li>Service Catalog to Service Catalog: Openslice able to consume and provide Service Catalog items to other catalogs</li> <li>Service Order: The Customer will be able to place a Service Order</li> <li>Service Inventory: The Customer and Provider will be able to view deployed Services status</li> </ul> <p>The following figure displays the overall architecture of Openslice.</p> <p></p> <p>Openslice allows Vertical Customers browsing the available offered service specifications. It consists of:</p> <ul> <li>Web frontend UIs that consist of mainly two portals: i) a NFV portal allowing users self-service management and onboarding VNFDs/NSDs to facility\u2019s NFVO ii) a Services Portal, which allows users to browse the Service Catalog, Service Blueprints specifications and the Service Inventory</li> <li>An API gateway that proxies the internal APIs and used by the web front end as well as any other 3rd party service</li> <li>A Message Bus where all microservices use it to exchange messages either via message queues or via publish/subscribe topics</li> <li>An authentication server implementing Oauth2 authentication scheme</li> <li>A microservice offering TMF compliant API services (eg Service Catalog API, Service Ordering APIetc)</li> <li>A microservice offering NFV API services (eg VNF/NSD onboarding etc) and allows to store VNFDs and NSDs in a catalog</li> <li>A microservice that is capable to interface to an issue management system. For example it raises an issue to all related stakeholders (CSP, NOP, CSC) that a new Service Order is requested</li> <li>Central logging microservice that is capable to log all distributed actions in to an Elasticsearch cluster</li> <li>A Service Orchestrator solution that will propagate Service Ordering requests to the equivalent SOs and NFVOs </li> </ul> <p>The following figure depicts how Openslice microservices are deployed</p> <p></p>"},{"location":"architecture/architecture/#deploying-openslice-in-multi-domain-scenarios","title":"Deploying Openslice in multi domain scenarios","text":"<p>A typical deployment across domains, involves today some typical components: i) an OSS/BSS to allow customers access the service catalog and perform service orders, ii) a Service Orchestrator (SO) component for executing the service order workflow, as well as iii) a Network Functions Virtualization Orchestrator (NFVO) for configuring the iv) network resources.</p> <p>TMF Open APIs are introduced not only for exposing catalogues and accepting service orders, but also implementing the East-West interfaces between the domains, fulfilling also the LSO requirements as introduced by MEF.</p> <p>The following figure shows how openslice could be used in such scenarios:</p> <p></p> <p>See more Consuming Services From External Partner Organizations</p>"},{"location":"architecture/centrallog/","title":"Central Logging","text":"<p>Openslice follows the centralized log management concept, i.e. a type of logging solution system that consolidates the log data from different services and pushes it to a central, accessible and easy-to-use interface. </p> <p>For that reason, Elasticsearch is elected as an open-source centralized logging solution for collecting, parsing and storing logs towards a real-time data analytics tool that provides insights from any type of structured and unstructured data source.</p>"},{"location":"architecture/consumingServicesFromExternalPartners/","title":"Consuming Services From External Partner Organizations","text":"<p>A typical deployment across domains, involves today some typical components: i) an OSS/BSS to allow customers access the service catalog and perform service orders, ii) a Service Orchestrator (SO) component for executing the service order workflow, as well as iii) a Network Functions Virtualization Orchestrator (NFVO) for configuring the iv) network resources.</p> <p>TMF Open APIs are introduced not only for exposing catalogues and accepting service orders, but also implementing the East-West interfaces between the domains, fulfilling also the LSO requirements as introduced by MEF.</p> <p>The following figure shows how openslice could be used in such scenarios:</p> <p></p> <p>In Openslice we can consume services from 3rd parties via Open APIs.</p> <p>We use the TMF 632 Party Management model to specify Organizations that we can exchange items and other information such as:</p> <ul> <li>Import Service Specifications</li> <li>Create a Service Order</li> <li>Use the Service Inventory to query the status of the service ordered to the external partner organization</li> </ul>"},{"location":"architecture/consumingServicesFromExternalPartners/#define-an-organization-as-3rd-party-to-consume-services-east-west","title":"Define an Organization as 3rd party to consume services East-West","text":"<p>An organization must have the following characteristics in openslice catalog, like for example:</p> <p>\"EXTERNAL_TMFAPI_BASEURL\", \"http://portal.openslice.io\"</p> <p>\"EXTERNAL_TMFAPI_CLIENTREGISTRATIONID\", \"authOpensliceProvider\"</p> <p>\"EXTERNAL_TMFAPI_OAUTH2CLIENTID\", \"osapiWebClientId\"</p> <p>\"EXTERNAL_TMFAPI_OAUTH2CLIENTSECRET\", \"secret\"</p> <p>\"EXTERNAL_TMFAPI_OAUTH2SCOPES\", scopes</p> <p>\"EXTERNAL_TMFAPI_OAUTH2TOKENURI\", \"http://portal.openslice.io/osapi-oauth-server/oauth/token\"</p> <p>\"EXTERNAL_TMFAPI_USERNAME\", \"admin\"</p> <p>\"EXTERNAL_TMFAPI_PASSWORD\", \"openslice\"</p> <p>\"EXTERNAL_TMFAPI_SERVICE_CATALOG_URLS\" = \"/tmf-api/serviceCatalogManagement/v4/serviceSpecification?type=CustomerFacingServiceSpecification\" (this is optional, fetch a list of service specs it will be relative with the BASEURL. If the url is empty then no specs will be fetched, the EXTERNAL_TMFAPI_SERVICE_CATEGORY_URLS might be used)</p> <p>\"EXTERNAL_TMFAPI_SERVICE_CATEGORY_URLS\" = \"/tmf-api/serviceCatalogManagement/v4/serviceCategory/{categoryid}\" (this example will fetch all specs in a category. You may define comma separated URLs of categories API URL . This will fetch specifications of every defined category. If you want only one specific category put for example the uuid only of one category: \"/tmf-api/serviceCatalogManagement/v4/serviceCategory/bda02821-bc4d-4bd6-b64b-d9c2aa5f8e6d\". multiple urls should be \"/tmf-api/serviceCatalogManagement/v4/serviceCategory/bda02821-bc4d-4bd6-b64b-d9c2aa5f8e6d,/tmf-api/serviceCatalogManagement/v4/serviceCategory/9b6d8bf3-abd2-43c4-8154-c8c6fe5545b2\")</p> <p>\"EXTERNAL_TMFAPI_SERVICE_SPEC\" = \"/tmf-api/serviceCatalogManagement/v4/serviceSpecification\"</p> <p>\"EXTERNAL_TMFAPI_SERVICE_ORDER_URLS\"= \"/test/v1/serviceorder\" (this is optional)</p> <p>An example Organization defined example in json:</p> <pre><code>\n{\n \"uuid\": \"1a09a8b5-6bd5-444b-b0b9-a73c69eb42ae\",\n \"@baseType\": \"BaseEntity\",\n \"@schemaLocation\": null,\n \"@type\": null,\n \"href\": null,\n \"name\": \"Openslice.io\",\n \"id\": \"1a09a8b5-6bd5-444b-b0b9-a73c69eb42ae\",\n \"isHeadOffice\": null,\n \"isLegalEntity\": null,\n \"nameType\": null,\n \"organizationType\": null,\n \"tradingName\": null,\n \"contactMedium\": [],\n \"creditRating\": [],\n \"existsDuring\": null,\n \"externalReference\": [],\n \"organizationChildRelationship\": [],\n \"organizationIdentification\": [],\n \"organizationParentRelationship\": null,\n \"otherName\": [],\n \"partyCharacteristic\": [\n {\n \"uuid\": \"3a2f7221-e0a2-4a6b-88d1-534c8e1963f6\",\n \"@baseType\": \"BaseEntity\",\n \"@schemaLocation\": null,\n \"@type\": null,\n \"href\": null,\n \"name\": \"EXTERNAL_TMFAPI_CLIENTREGISTRATIONID\",\n \"valueType\": null,\n \"value\": {\n \"value\": \"authOpensliceProvider\",\n \"alias\": null\n }\n },\n {\n \"uuid\": \"c24bb527-f178-4d38-9b93-2027c1732876\",\n \"@baseType\": \"BaseEntity\",\n \"@schemaLocation\": null,\n \"@type\": null,\n \"href\": null,\n \"name\": \"EXTERNAL_TMFAPI_USERNAME\",\n \"valueType\": null,\n \"value\": {\n \"value\": \"admin\",\n \"alias\": null\n }\n },\n {\n \"uuid\": \"27e45df8-414b-44c6-a5d5-3f064e2cfd3b\",\n \"@baseType\": \"BaseEntity\",\n \"@schemaLocation\": null,\n \"@type\": null,\n \"href\": null,\n \"name\": \"EXTERNAL_TMFAPI_PASSWORD\",\n \"valueType\": null,\n \"value\": {\n \"value\": \"openslice\",\n \"alias\": null\n }\n },\n {\n \"uuid\": \"e0e470b8-6024-4014-8a18-2333e5465ce1\",\n \"@baseType\": \"BaseEntity\",\n \"@schemaLocation\": null,\n \"@type\": null,\n \"href\": null,\n \"name\": \"EXTERNAL_TMFAPI_OAUTH2CLIENTSECRET\",\n \"valueType\": null,\n \"value\": {\n \"value\": \"secret\",\n \"alias\": null\n }\n },\n {\n \"uuid\": \"3e0de762-ac80-4c1e-a0a1-f265ff0899b4\",\n \"@baseType\": \"BaseEntity\",\n \"@schemaLocation\": null,\n \"@type\": null,\n \"href\": null,\n \"name\": \"EXTERNAL_TMFAPI_OAUTH2SCOPES\",\n \"valueType\": null,\n \"value\": {\n \"value\": \"admin;read\",\n \"alias\": null\n }\n },\n {\n \"uuid\": \"0bbb8314-f7f2-420d-9fed-ba054b15f886\",\n \"@baseType\": \"BaseEntity\",\n \"@schemaLocation\": null,\n \"@type\": null,\n \"href\": null,\n \"name\": \"EXTERNAL_TMFAPI_OAUTH2TOKENURI\",\n \"valueType\": null,\n \"value\": {\n \"value\": \"http://portal.openslice.io/osapi-oauth-server/oauth/token\",\n \"alias\": null\n }\n },\n {\n \"uuid\": \"3a567de4-79eb-4006-a500-3e5229b44175\",\n \"@baseType\": \"BaseEntity\",\n \"@schemaLocation\": null,\n \"@type\": null,\n \"href\": null,\n \"name\": \"EXTERNAL_TMFAPI_OAUTH2CLIENTID\",\n \"valueType\": null,\n \"value\": {\n \"value\": \"osapiWebClientId\",\n \"alias\": null\n }\n },\n {\n \"uuid\": \"6dca729f-dbe1-46b7-89f1-5c4f9fe89d4e\",\n \"@baseType\": \"BaseEntity\",\n \"@schemaLocation\": null,\n \"@type\": null,\n \"href\": null,\n \"name\": \"EXTERNAL_TMFAPI_BASEURL\",\n \"valueType\": null,\n \"value\": {\n \"value\": \"http://portal.openslice.io\",\n \"alias\": null\n }\n }\n ],\n \"relatedParty\": [],\n \"status\": null,\n \"taxExemptionCertificate\": []\n}\n\n</code></pre>"},{"location":"architecture/issuemgt/","title":"Issue Management","text":"<p>For issue management support, Openslice relies on Bugzilla. Bugzilla is a ticketing tool that allows issue reporting and tracking via tickets to all relevant stakeholders. </p> <p>The figure below displays the overall issue management service architecture integrating Bugzilla as its core and how this tool interacts with other Openslice services presenting some distinctive scenarios. It should be noted that Bugzilla tickets will not only be used for bugs/errors, but also for general requests, e.g. Service Order procedure.</p> <p></p>"},{"location":"architecture/messagebus/","title":"Message Bus and exchanged Messages","text":"<p>Openslice has a Message bus which allows Openslice services to exchange messages via queues and topics.</p> <p>It is based on ActiveMQ.</p> <p>3rd party services can be attached to bus and subscribe to message topics or request resources via queues.</p>"},{"location":"architecture/messagebus/#queue-messages","title":"QUEUE MESSAGES","text":"Message Alias CATALOG_GET_SERVICEORDERS Name jms:queue:CATALOG.GET.SERVICEORDERS Type queue Destination TMF API service Producers OSOM Body Description Return a List as String Json Message Alias CATALOG_GET_SERVICEORDER_BY_ID Name jms:queue:CATALOG.GET.SERVICEORDER_BY_ID Type queue Destination TMF API service Producers OSOM Body String orderid Description Return a ServiceOrder as String Json Message Alias CATALOG_UPD_SERVICEORDER_BY_ID Name jms:queue:CATALOG.UPD.SERVICEORDER_BY_ID Type queue Destination TMF API service Producers OSOM Body ServiceOrderUpdate serviceOrder Headers \"orderid\"= orderid Description Returns a ServiceOrder as String Message Alias CATALOG_GET_SERVICESPEC_BY_ID Name jms:queue:CATALOG.GET.SERVICESPEC_BY_ID Type queue Destination TMF API service Producers OSOM Body specid Description Return a ServiceSpecification Message Alias CATALOG_ADD_SERVICESPEC Name jms:queue:CATALOG.ADD.SERVICESPEC Type queue Destination TMF API service Producers CRIDGE Body ServiceSpecCreate Description Creates a ServiceSpecification and returns a ServiceSpecification as String Message Alias CATALOG_UPD_SERVICESPEC Name jms:queue:CATALOG.UPD.SERVICESPEC Type queue Destination TMF API service Producers CRIDGE Body ServiceSpecUpdate Headers \"serviceSpecid\" = serviceSpecId Description Updates a ServiceSpecification and returns a ServiceSpecification as String. --- Message Alias CATALOG_UPDADD_SERVICESPEC Name jms:queue:CATALOG.UPDADD.SERVICESPEC Type queue Destination TMF API service Producers CRIDGE Body ServiceSpecUpdate Headers \"serviceSpecid\" = serviceSpecId, \"forceId\"=forceId Description Updates a ServiceSpecification and returns a ServiceSpecification as String. If forceId is true then tries to assign the requested ID to the spec Message Alias CATALOG_ADD_SERVICEORDER Name jms:queue:CATALOG.ADD.SERVICEORDER Type queue Destination TMF API service Producers OSOM Body ServiceOrderCreate serviceOrder Headers Description Creates a ServiceOrder and returns a ServiceOrder as String Message Alias CATALOG_GET_INITIAL_SERVICEORDERS_IDS Name jms:queue:CATALOG.GET.INITIAL_SERVICEORDERS Type queue Destination TMF API service Producers Body Description Return a List as String Json Message Alias CATALOG_GET_SERVICEORDER_IDS_BY_STATE Name jms:queue:CATALOG.GET.ACKNOWLEDGED_SERVICEORDERS Type queue Destination TMF API service Producers OSOM Body Headers \"orderstate\"= orderState Description String Json ArrayList of ServiceOrders Message Alias CATALOG_ADD_SERVICE Name jms:queue:CATALOG.ADD.SERVICE Type queue Destination TMF API service Producers OSOM Body ServiceCreate String json Headers \"orderid\"=orderid, \"serviceSpecid\"= specid Description Creates Service based an a Service Spec, Returns a Service object Message Alias CATALOG_UPD_SERVICE Name jms:queue:CATALOG.UPD.SERVICE Type queue Destination TMF API service Producers Body ServiceUpdate Headers \"serviceid\" = serviceId, \"propagateToSO\" = true/false Description will update a service by id and return the service instance. If propagateToSO=true then any service change will be handled by OSOM. This is needed to be controlled in order to avoid update loops Message Alias CATALOG_GET_SERVICE_BY_ID Name jms:queue:CATALOG.GET.SERVICE Type queue Destination TMF API service Producers OSOM Body String serviceID Description returns a Service instance <p>---| Message | | | ------------- |----------------| |Alias | CATALOG_GET_SERVICE_BY_ORDERID | |Name | jms:queue:CATALOG.GET.SERVICE_BY_ORDERID | |Type | queue | |Destination | TMF API service | |Producers | | |Body | String serviceID | |Description | returns Service IDs of a specific order given then order id |</p> Message Alias CATALOG_SERVICE_QUEUE_ITEMS_GET Name jms:queue:CATALOG.SERVICEQUEUEITEMS.GET Type queue Destination TMF API service Producers OSOM Body Description returns a LIST OF Service Queue Items --- Message Alias CATALOG_SERVICE_QUEUE_ITEM_UPD Name jms:queue:CATALOG.SERVICEQUEUEITEM.UPDATE Type queue Destination TMF API service Producers OSOM Body String SERVICEQUEUEITEM Headers \"itemid\" = SERVICEQUEUEITEM id Description ill update a service queue item by id and return the instance --- Message Alias CATALOG_SERVICE_QUEUE_ITEM_DELETE Name jms:queue:CATALOG.SERVICEQUEUEITEM.DELETE Type queue Destination TMF API service Producers OSOM Body Headers \"itemid\" = SERVICEQUEUEITEM id Description ill delete a service queue item by id Message Alias CATALOG_SERVICES_TO_TERMINATE Name jms:queue:CATALOG.GET.SERVICETOTERMINATE Type queue Destination TMF API service Producers OSOM Body Headers Description Get a list of ACTIVE services with END DAte in the past --- Message Alias CATALOG_SERVICES_OF_PARTNERS Name jms:queue:CATALOG.GET.SERVICESOFPARTNERS Type queue Destination TMF API service Producers OSOM Body Headers Description Get a list of ACTIVE services from the inventory of partners Message Alias NFV_CATALOG_GET_NSD_BY_ID Name jms:queue:NFVCATALOG.GET.NSD_BY_ID Type queue Destination NFV Catalog service Producers TMF API, OSOM Body NSDid Description Returns a NetworkServiceDescriptor object Message Alias NFV_CATALOG_DEPLOY_NSD_REQ Name jms:queue:NFVCATALOG.DEPLOY.NSD_REQ Type queue Destination NFV Catalog service Producers OSOM Body DeploymentDescriptor as Json String Headers NSD id Description Returns a DeploymentDescriptor object as json string containing deployment info Message Alias NFV_CATALOG_UPD_DEPLOYMENT_BY_ID Name jms:queue:NFVCATALOG.UPD.DEPLOYMENT_BY_ID Type queue Destination NFV Catalog service Producers OSOM Body DeploymentDescriptor as Json String Headers DeploymentDescriptor id Description Updates and Returns a DeploymentDescriptor object as json string containing deployment info Message Alias GET_USER_BY_USERNAME Name jms:queue:GET.USER_BY_USERNAME Type queue Destination NFV Catalog service (this is temproary for now) Producers TMF API Body username Headers Description Returns a PortalUser object as json string containing user info Message Alias NFV_CATALOG_GET_DEPLOYMENT_BY_ID Name jms:queue:NFVCATALOG.GET.DEPLOYMENT_BY_ID Type queue Destination NFV Catalog service Producers OSOM Body Deployment ID Description Returns a DeploymentDescriptor object Message Alias CATALOG_GET_EXTERNAL_SERVICE_PARTNERS Name jms:queue:CATALOG.GET.EXTERNALSERVICEPARTNERS Type queue Destination TMF API service Producers OSOM Body Headers Description As a String Json ArrayList of Organizaton objects containing the characteristic name EXTERNAL_TMFAPI Message Alias CATALOG_UPD_EXTERNAL_SERVICESPEC Name jms:queue:CATALOG.UPD.EXTERNAL_SERVICESPEC Type queue Destination TMF API service Producers OSOM or maybe used by others that would like to update a Service Spec Body A serviceSpecification as json string Headers servicespecification id, orgid id Description Updates (or inserts if does not exist in catalog) an external service specification) Message Alias NFV_CATALOG_NSACTIONS_SCALE Name jms:queue:NSACTIONS.SCALE Type queue Destination TMF API service Producers OSOM or maybe used by others that would like scale a NS Body A ScaleDescriptor as json string Headers none Description performs a scale Message Alias NFV_CATALOG_NS_LCMCHANGED Name NFV_CATALOG_NS_LCMCHANGED Type topic Destination any Producers MANO client Body A json string Headers none Description A NFV_CATALOG_NS_LCMCHANGED message is published when LCM of a running NS is changed"},{"location":"architecture/messagebus/#alarms","title":"ALARMS","text":"Message Alias ALARMS_ADD_ALARM Name jms:queue:ALARMS.ADD.ALARM Type queue Publishers Consumers TMF API Body AlarmCreate Headers Description Add an alarm Message Alias ALARMS_UPDATE_ALARM Name jms:queue:ALARMS.UPDATE.ALARM Type queue Publishers Consumers TMF API Body AlarmUpdate Headers alarmid = alarm id, body (AlarmUpdate object) Description Update an alarm Message Alias ALARMS_GET_ALARM Name jms:queue:ALARMS.GET.ALARM Type queue Publishers Consumers TMF API Body Headers alarmid = alarm id Description get an alarm"},{"location":"architecture/messagebus/#event-topics-in-message-bus","title":"EVENT TOPICS IN Message Bus","text":"Message Alias EVENT_SERVICE_CREATE Name jms:topic:EVENT.SERVICE.CREATE Type topic Publishers TMF API Consumers - Body Notification object Headers \"eventid\"=eventid, \"objId\"= objId Description xx Message Alias EVENT_SERVICE_STATE_CHANGED Name jms:topic:EVENT.SERVICE.STATECHANGED Type topic Publishers TMF API Consumers - Body Notification object Headers \"eventid\"=eventid, \"objId\"= objId Description xx Message Alias EVENT_SERVICE_DELETE Name jms:topic:EVENT.SERVICE.DELETE Type topic Publishers TMF API Consumers - Body Notification object. Can be one of ServiceOrderCreateNotification, ServiceOrderStateChangeNotification, ServiceOrderAttributeValueChangeNotification, ServiceOrderDeleteNotification, etc Headers \"eventid\"=eventid, \"objId\"= objId Description xx Message Alias EVENT_SERVICE_ATTRIBUTE_VALUE_CHANGED Name jms:topic:EVENT.SERVICE.ATTRCHANGED Type topic Publishers TMF API Consumers - Body Notification object. Can be one of ServiceOrderCreateNotification, ServiceOrderStateChangeNotification, ServiceOrderAttributeValueChangeNotification, ServiceOrderDeleteNotification, etc Headers \"eventid\"=eventid, \"objId\"= objId Description xx Message Alias EVENT_SERVICE_ORDER_CREATE Name jms:topic:EVENT.SERVICEORDER.CREATE Type topic Publishers TMF API Consumers BUGZILLA Service, CentralLog Service Body Notification object. Can be one of ServiceOrderCreateNotification, ServiceOrderStateChangeNotification, ServiceOrderAttributeValueChangeNotification, ServiceOrderDeleteNotification, etc Headers \"eventid\"=eventid, \"objId\"= objId Description The Event of the Notification object contains the ServiceOrder object. Bugzilla service for example uses this to create a new issue Message Alias EVENT_SERVICE_ORDER_STATE_CHANGED Name jms:topic:EVENT.SERVICEORDER.STATECHANGED Type topic Publishers TMF API Consumers BUGZILLA Service, CentralLog Service Body Notification object. Can be one of ServiceOrderCreateNotification, ServiceOrderStateChangeNotification, ServiceOrderAttributeValueChangeNotification, ServiceOrderDeleteNotification, etc Headers \"eventid\"=eventid, \"objId\"= objId Description The Event of the Notification object contains the ServiceOrder object. Bugzilla service for example uses this to update an issue Message Alias EVENT_SERVICE_ORDER_DELETE Name jms:topic:EVENT.SERVICEORDER.DELETE Type topic Publishers TMF API Consumers BUGZILLA Service, CentralLog Service Body Notification object. Can be one of ServiceOrderCreateNotification, ServiceOrderStateChangeNotification, ServiceOrderAttributeValueChangeNotification, ServiceOrderDeleteNotification, etc Headers \"eventid\"=eventid, \"objId\"= objId Description The Event of the Notification object contains the ServiceOrder object Message Alias EVENT_SERVICE_ORDER_ATTRIBUTE_VALUE_CHANGED Name jms:topic:EVENT.SERVICEORDER.ATTRCHANGED Type topic Publishers TMF API Consumers BUGZILLA Service, CentralLog Service Body Notification object. Can be one of ServiceOrderCreateNotification, ServiceOrderStateChangeNotification, ServiceOrderAttributeValueChangeNotification, ServiceOrderDeleteNotification, etc Headers \"eventid\"=eventid, \"objId\"= objId Description The Event of the Notification object contains the ServiceOrder object Message Alias EVENT_ALARM_CREATE Name jms:topic:EVENT.ALARM.CREATE Type topic Publishers TMF API Consumers OAS, BUGZILLA Service, CentralLog Service Body AlarmCreateEvent Headers Description The Event contains the Alarm object in payload Message Alias CATALOG_ADD_RESOURCE Name jms:queue:CATALOG.ADD.RESOURCE Type topic Publishers TMF API Consumers any Body ResourceCreate Headers Description The Body contains the ResourceCreate object to add Message Alias CATALOG_UPD_RESOURCE Name jms:queue:CATALOG.UPD.RESOURCE Type topic Publishers TMF API Consumers any Body ResourceUpdate Headers resourceid , propagateToSO Description The Body contains the ResourceCreate object to update Message Alias CATALOG_GET_RESOURCE_BY_ID Name jms:queue:CATALOG.GET.RESOURCE Type topic Publishers TMF API Consumers any Body resourceid Headers Description The Body contains the ResourceCreate object to update Message Alias CATALOG_RESOURCES_OF_PARTNERS Name jms:queue:CATALOG.GET.SERVICESOFPARTNERS Type topic Publishers TMF API Consumers any Body none Headers none Description retrieve all active services of partners Message Alias CATALOG_ADD_RESOURCESPEC Name jms:queue:CATALOG.ADD.RESOURCESPEC Type topic Publishers TMF API Consumers any Body ResourceSpecificationCreate Headers Description The Body contains the ResourceSpecificationCreate object to add Message Alias CATALOG_UPD_RESOURCESPEC Name jms:queue:CATALOG.UPD.RESOURCESPEC Type topic Publishers TMF API Consumers any Body ResourceSpecificationUpdate Headers resourceSpecId Description The Body contains the ResourceSpecificationCreate object to update Message Alias CATALOG_GET_RESOURCESPEC_BY_ID Name jms:queue:CATALOG.GET.RESOURCESPEC_BY_ID Type topic Publishers TMF API Consumers any Body resourceSpecid Headers Description The Body contains the object id to find Message Alias CATALOG_UPDADD_RESOURCESPEC Name jms:queue:CATALOG.UPDADD.RESOURCESPEC Type topic Publishers TMF API Consumers any Body resourceid Headers Description The Body contains the ResourceSpecificationCreate object to update or create if not exist Message Alias EVENT_RESOURCE_CREATE Name jms:topic:EVENT.RESOURCE.CREATE Type topic Publishers TMF API Consumers BUGZILLA Service, CentralLog Service, other Body Notification object. Headers \"eventid\"=eventid, \"objId\"= objId Description The Event of the Notification object contains the Resource object Message Alias EVENT_RESOURCE_STATE_CHANGED Name jms:topic:EVENT.RESOURCE.STATECHANGED Type topic Publishers TMF API Consumers BUGZILLA Service, CentralLog Service, other Body Notification object. Headers \"eventid\"=eventid, \"objId\"= objId Description The Event of the Notification object contains the Resource object Message Alias EVENT_RESOURCE_DELETE Name jms:topic:EVENT.SERVICE.RESOURCE Type topic Publishers TMF API Consumers BUGZILLA Service, CentralLog Service, other Body Notification object. Headers \"eventid\"=eventid, \"objId\"= objId Description The Event of the Notification object contains the Resource object Message Alias EVENT_RESOURCE_ATTRIBUTE_VALUE_CHANGED Name jms:topic:EVENT.RESOURCE.ATTRCHANGED Type topic Publishers TMF API Consumers BUGZILLA Service, CentralLog Service, other Body Notification object. Headers \"eventid\"=eventid, \"objId\"= objId Description The Event of the Notification object contains the Resource object Message Alias CATALOG_GET_LCMRULE_BY_ID Name jms:queue:CATALOG.GET.LCMRULE Type topic Publishers TMF API Consumers any Body lcmid Headers Description The Body contains the LCMRuleSpec object Message Alias CATALOG_GET_LCMRULES_BY_SPECID_PHASE Name jms:queue:CATALOG.GET.LCMRULES_BY_SPECID_PHASE Type topic Publishers TMF API Consumers any Body Headers header.servicespecid, header.phasename Description The Body contains the LCMRuleSpec objects of the specific Service Spec and the specific phase Message Alias CATALOG_GET_SERVICETESTSPEC_BY_ID Name jms:queue:CATALOG.GET.SERVICETESTSPEC_BY_ID Type queue Destination TMF API service Producers OSOM Body specid Description Return a ServiceTestSpecification Message Alias CATALOG_ADD_SERVICETEST Name jms:queue:CATALOG.ADD.SERVICETEST Type queue Destination TMF API service Producers OSOM Body ServiceTestCreate String json Headers \"orderid\"=orderid, \"serviceTestSpecid\"= specid Description Creates Service Test based an a Service Test Spec, Returns a ServiceTest object Message Alias CATALOG_UPD_SERVICETEST Name jms:queue:CATALOG.UPD.SERVICETEST Type queue Destination TMF API service Producers Body ServiceTestUpdate Headers \"serviceid\" = serviceId, \"propagateToSO\" = true/false Description will update a service test by id and return the service instance. If propagateToSO=true then any service change will be handled by OSOM. This is needed to be controlled in order to avoid update loops Message Alias CATALOG_GET_SERVICETEST_BY_ID Name jms:queue:CATALOG.GET.SERVICETEST Type queue Destination TMF API service Producers OSOM Body String serviceID Description returns a Service TEST instance Message Alias CRD_DEPLOY_CR_REQ Name jms:queue:CRD.DEPLOY.CR_REQ Type queue Destination CRD service Producers OSOM Body CR spec as String Headers related service id Description Returns a String object containing deployment info Message Alias CRD_PATCH_CR_REQ Name jms:queue:CRD.PATCH.CR_REQ Type queue Destination CRD service Producers OSOM Body CR as String Headers related service id Description Returns a String object containing PATCH info Message Alias CRD_DELETE_CR_REQ Name jms:queue:CRD.DELETE.CR_REQ Type queue Destination CRD service Producers OSOM Body CR as String Headers related service id Description Returns a String object containing deletion info"},{"location":"architecture/nfvapi/","title":"API interaction","text":""},{"location":"architecture/nfvapi/#oauth-token","title":"OAuth token","text":"<p>See oauth</p>"},{"location":"architecture/nfvapi/#request-a-protected-api-resource","title":"Request a protected API resource","text":"<p>Example: Get all vxfs (check the <code>Authorization:Bearer</code> to be correct)</p> <pre><code>curl -H \"Authorization:Bearer eybGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX25hbWUiOiJhZG1pbiIsInNjb3BlIjpbIm9wZW5hcGkiLCJhZG1pbiIsInJlYWQiLCJ3cml0ZSJdLCJvcmdhbml6YXRpb24iOiJteW9yZ2FuaXp0aW9uIiwiZXhwIjoxNTcxOTI0MjU2LCJhdXRob3JpdGllcyI6WyJST0xFX01FTlRPUiIsIlJPTEVfQURNSU4iXSwianRpIjoiNzNkZmIxODEtNTMwOS00MmExLThkOWUtOGM3YmQ0YTE1YmU0IiwiY2xpZW50X2lkIjoib3NhcGlXZWJDbGllbnRJZE91dCJ9.Pj_hxnyMGhFhN8avU_DiAw1-LlcaIz5Hp9HNqalw-X4\" http://localhost:13000/osapi/admin/vxfs\n</code></pre> <p>Example response:</p> <pre><code>[\n {\n \"id\": 1,\n \"owner\": {\n \"id\": 1,\n \"organization\": \"ee\",\n \"name\": \"Portal Administrator\",\n \"email\": \"\",\n \"username\": \"admin\",\n \"createdAt\": null\n },\n \"uuid\": \"a954daf2-16da-4b7e-ae42-4825936d453c\",\n \"name\": \"cirros_vnfd\",\n \"iconsrc\": \"/osapi/images/a954daf2-16da-4b7e-ae42-4825936d453c/cirros-64.png\",\n \"shortDescription\": \"cirros_vnfd\",\n \"longDescription\": \"Simple VNF example with a cirros\",\n \"version\": \"1.0\",\n \"packageLocation\": \"/osapi/packages/a954daf2-16da-4b7e-ae42-4825936d453c/cirros_vnf.tar.gz\",\n \"dateCreated\": 1568971426000,\n \"dateUpdated\": 1568981107000,\n \"categories\": [\n {\n \"id\": 3,\n \"name\": \"Service\",\n \"productsCount\": 1,\n \"appscount\": 0,\n \"vxFscount\": 1\n },\n {\n \"id\": 2,\n \"name\": \"Networking\",\n \"productsCount\": 1,\n \"appscount\": 0,\n \"vxFscount\": 1\n }\n ],\n \"extensions\": [],\n \"validationJobs\": [],\n \"screenshots\": \"\",\n \"vendor\": \"OSM\",\n \"published\": false,\n \"termsOfUse\": null,\n \"descriptor\": \"vnfd-catalog:\\n vnfd:\\n - connection-point:\\n - name: eth0\\n type: VPORT\\n description: Simple VNF example with a cirros\\n id: cirros_vnfd\\n logo: cirros-64.png\\n mgmt-interface:\\n cp: eth0\\n name: cirros_vnfd\\n short-name: cirros_vnfd\\n vdu:\\n - count: 1\\n description: cirros_vnfd-VM\\n id: cirros_vnfd-VM\\n image: cirros034\\n interface:\\n - external-connection-point-ref: eth0\\n name: eth0\\n position: '1'\\n type: EXTERNAL\\n virtual-interface:\\n bandwidth: '0'\\n type: VIRTIO\\n vpci: 0000:00:0a.0\\n name: cirros_vnfd-VM\\n vm-flavor:\\n memory-mb: 512\\n storage-gb: 1\\n vcpu-count: 1\\n vendor: OSM\\n version: '1.0'\\n\",\n \"descriptorHTML\": \"<h3>cirros_vnfd</h3><br><b>Vendor: </b>OSM<br><b>Version: </b>1.0<br><b>Description: </b>Simple VNF example with a cirros<br><b>VM Count: </b>1<br><b>vCPU Count: </b>1<br><b>Memory: </b>512 MB<br><b>Storage: </b>1 GB<br>\",\n \"certified\": false,\n \"certifiedBy\": null,\n \"validationStatus\": \"UNDER_REVIEW\",\n \"packagingFormat\": \"OSMvFIVE\",\n \"supportedMANOPlatforms\": [\n {\n \"id\": 1,\n \"name\": \"osm fivee\",\n \"version\": \"osm fivee\",\n \"description\": \"osm five\"\n }\n ],\n \"vxfOnBoardedDescriptors\": [],\n \"vfimagesVDU\": [\n {\n \"id\": 1,\n \"name\": \"cirros034\",\n \"uuid\": \"d4549610-8abd-42ad-97f4-0a64e1c93977\",\n \"shortDescription\": \"Automatically created during vxf cirros_vnfd submission. Owner must update.\",\n \"packageLocation\": null,\n \"publicURL\": null,\n \"dateCreated\": 1568971426000,\n \"dateUpdated\": null,\n \"refVxFs\": [\n {\n \"id\": 1,\n \"name\": \"cirros_vnfd\"\n }\n ],\n \"owner\": {\n \"id\": 1,\n \"organization\": \"ee\",\n \"name\": \"Portal Administrator\",\n \"email\": \"\",\n \"username\": \"admin\",\n \"active\": true,\n \"currentSessionID\": null,\n \"apikey\": \"e41c1cc4-aa56-4b7e-9f4d-64589549d768\",\n \"createdAt\": 1568711859000,\n \"roles\": [\n \"ADMIN\",\n \"MENTOR\"\n ]\n },\n \"published\": false,\n \"termsOfUse\": null,\n \"deployedInfrastructures\": []\n }\n ]\n },\n {\n \"id\": 2,\n \"owner\": {\n \"id\": 1,\n \"organization\": \"ee\",\n \"name\": \"Portal Administrator\",\n \"email\": \"\",\n \"username\": \"admin\",\n \"createdAt\": null\n },\n \"uuid\": \"4ab80095-a63e-4fe7-8598-e1c7e880706e\",\n \"name\": \"cirros_sriov_vnfd\",\n \"iconsrc\": null,\n \"shortDescription\": \"cirros_sriov_vnf\",\n \"longDescription\": \"Simple VNF example with a cirros SRIOV interface\",\n \"version\": \"1.0\",\n \"packageLocation\": \"/osapi/packages/4ab80095-a63e-4fe7-8598-e1c7e880706e/cirros_sriov.tar.gz\",\n \"dateCreated\": 1568971740000,\n \"dateUpdated\": 1568981100000,\n \"categories\": [\n {\n \"id\": 4,\n \"name\": \"tyu\",\n \"productsCount\": 1,\n \"appscount\": 0,\n \"vxFscount\": 1\n },\n {\n \"id\": 5,\n \"name\": \"tyi\",\n \"productsCount\": 1,\n \"appscount\": 0,\n \"vxFscount\": 1\n }\n ],\n \"extensions\": [],\n \"validationJobs\": [],\n \"screenshots\": \"\",\n \"vendor\": \"OSM\",\n \"published\": false,\n \"termsOfUse\": null,\n \"descriptor\": \"vnfd:vnfd-catalog:\\n vnfd:\\n - connection-point:\\n - name: eth0\\n type: VPORT\\n - name: eth1\\n type: VPORT\\n description: Simple VNF example with a cirros SRIOV interface\\n id: cirros_sriov_vnfd\\n logo: cirros-64.png\\n mgmt-interface:\\n cp: eth0\\n name: cirros_sriov_vnf\\n short-name: cirros_sriov_vnf\\n vdu:\\n - count: 1\\n description: cirros_sriov_vnfd-VM\\n guest-epa:\\n cpu-pinning-policy: DEDICATED\\n cpu-thread-pinning-policy: PREFER\\n mempage-size: SMALL\\n numa-node-policy:\\n mem-policy: STRICT\\n node:\\n - id: '1'\\n node-cnt: '1'\\n id: cirros_sriov_vnfd-VM\\n image: cirros-0.3.6-x86_64\\n interface:\\n - external-connection-point-ref: eth0\\n name: eth0\\n position: '1'\\n type: EXTERNAL\\n virtual-interface:\\n bandwidth: '0'\\n type: VIRTIO\\n vpci: 0000:00:0a.0\\n - external-connection-point-ref: eth1\\n name: eth1\\n position: '2'\\n type: EXTERNAL\\n virtual-interface:\\n type: SR-IOV\\n name: cirros_sriov_vnfd-VM\\n vm-flavor:\\n memory-mb: 4096\\n storage-gb: 10\\n vcpu-count: 4\\n vendor: OSM\\n version: '1.0'\\n\",\n \"descriptorHTML\": \"<h3>cirros_sriov_vnf</h3><br><b>Vendor: </b>OSM<br><b>Version: </b>1.0<br><b>Description: </b>Simple VNF example with a cirros SRIOV interface<br><b>VM Count: </b>1<br><b>vCPU Count: </b>1<br><b>Memory: </b>4096 MB<br><b>Storage: </b>10 GB<br>\",\n \"certified\": false,\n \"certifiedBy\": null,\n \"validationStatus\": \"UNDER_REVIEW\",\n \"packagingFormat\": \"OSMvFIVE\",\n \"supportedMANOPlatforms\": [\n {\n \"id\": 1,\n \"name\": \"osm fivee\",\n \"version\": \"osm fivee\",\n \"description\": \"osm five\"\n }\n ],\n \"vxfOnBoardedDescriptors\": [],\n \"vfimagesVDU\": [\n {\n \"id\": 2,\n \"name\": \"cirros-0.3.6-x86_64\",\n \"uuid\": \"be121176-1d62-4a1b-a3c1-7dce2e069d22\",\n \"shortDescription\": \"Automatically created during vxf cirros_sriov_vnfd submission. Owner must update.\",\n \"packageLocation\": null,\n \"publicURL\": null,\n \"dateCreated\": 1568971740000,\n \"dateUpdated\": null,\n \"refVxFs\": [\n {\n \"id\": 2,\n \"name\": \"cirros_sriov_vnfd\"\n }\n ],\n \"owner\": {\n \"id\": 1,\n \"organization\": \"ee\",\n \"name\": \"Portal Administrator\",\n \"email\": \"\",\n \"username\": \"admin\",\n \"active\": true,\n \"currentSessionID\": null,\n \"apikey\": \"e41c1cc4-aa56-4b7e-9f4d-64589549d768\",\n \"createdAt\": 1568711859000,\n \"roles\": [\n \"ROLE_ADMIN\",\n \"ROLE_MENTOR\"\n ]\n },\n \"published\": false,\n \"termsOfUse\": null,\n \"deployedInfrastructures\": []\n }\n ]\n }\n]\n</code></pre>"},{"location":"architecture/oauth/","title":"Authentication Server","text":"<p>Authentication is based on oAuth2. Our authentication service is a Keycloak server which is deployed with Openslice deployment </p> <p>API users needs to authenticate. All APIs (except grant token request) must include Bearer token in request Authorization header.</p>"},{"location":"architecture/oauth/#oauth-token","title":"OAuth token","text":"<p>Get first an oauth token, using your username and password. </p> <pre><code>curl -X POST http://portal.openslice.io/auth/realms/openslice/protocol/openid-connect/token -H 'Content-Type: application/x-www-form-urlencoded' -d 'username=demouser' -d 'password=demouser' -d 'grant_type=password' -d 'client_id=osapiWebClientId' \n</code></pre> <p>response:</p> <pre><code> {\"access_token\":\"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJHZFRjQnpxczg2VW10NTRVZV8ybTJyWHJkV3dzaWdSZE9EUldMYm1memNvIn0.eyJleHAiOjE1ODgyNDA1NzAsImlhdCI6MTU4ODI0MDI3MCwianRpIjoiOGI2ZTU0NWUtNDIyYy00NzFiLWEwN2UtYTUzYzY1NDQ0MzZmIiwiaXNzIjoiaHR0cDovL3BvcnRhbC5vcGVuc2xpY2UuaW8vYXV0aC9yZWFsbXMvb3BlbnNsaWNlIiwiYXVkIjoiYWNjb3VudCIsInN1YiI6ImExYTI3NjVhLWVjODMtNDQ1Ni1iN2IyLTIwNzMxOTg2ZTAzNSIsInR5cCI6IkJlYXJlciIsImF6cCI6Im9zYXBpV2ViQ2xpZW50SWQiLCJzZXNzaW9uX3N0YXRlIjoiMzM1MGY0OTMtNjYyNy00MzczLTg1NDQtZGVmZDI3YWQzYzc0IiwiYWNyIjoiMSIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjEzMDgyIiwiaHR0cDovL2xvY2FsaG9zdCIsImh0dHA6Ly9vcGVuc2xpY2UuaW8iLCJodHRwOi8vbG9jYWxob3N0OjEzMDAwIiwiaHR0cDovL2xvY2FsaG9zdDo0MjAwIiwiaHR0cDovL3BvcnRhbC5vcGVuc2xpY2UuaW8iXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIk5GVl9ERVZFTE9QRVIiLCJvZmZsaW5lX2FjY2VzcyIsInVtYV9hdXRob3JpemF0aW9uIiwiRVhQRVJJTUVOVEVSIiwiVVNFUiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoicHJvZmlsZSBlbWFpbCIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJkZW1vdXNlciJ9.TnzzpRLMD94UTKpT5_wkr1h4_3KUQmr4TGvFLpJ7cZx-Klrv8tB_eRkWnPqqzCAM9G21a1qXboL8MLMW8ECzG7HYKpobKOGr7LSczMOTdA2ZDyBCRUSOdW77pchu54tJ0ITEkFaDwSKMKKt04V_Sy4U-eIndj0XzzRlkDolWDnK4Z2lRaXAI6fMwOKx1Toa6RfOcemxtzl3pdtjPx92zo6MaKlbIqHK82lxdK0k8aQQaT6TmIrXbZKV2dU_1d3O0q0dVUEZJ_1kzwqOFkmxr9w0EnndC6ccYJlDAr_-GgUhhhNOn5v6tjYLUQdj5e4KEAsxIPzaCreK4un7mEAPmDw\",\"expires_in\":300,\"refresh_expires_in\":1800,\"refresh_token\":\"eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICIwZjUxMDk5Yy0wNTIzLTRjNGQtODM0Zi1iNDc0YzBjOTA1MzkifQ.eyJleHAiOjE1ODgyNDIwNzAsImlhdCI6MTU4ODI0MDI3MCwianRpIjoiZmViOTg5NWEtOTY5ZS00MzIzLWJjY2QtZTY2YzQ0NGE1MzJlIiwiaXNzIjoiaHR0cDovL3BvcnRhbC5vcGVuc2xpY2UuaW8vYXV0aC9yZWFsbXMvb3BlbnNsaWNlIiwiYXVkIjoiaHR0cDovL3BvcnRhbC5vcGVuc2xpY2UuaW8vYXV0aC9yZWFsbXMvb3BlbnNsaWNlIiwic3ViIjoiYTFhMjc2NWEtZWM4My00NDU2LWI3YjItMjA3MzE5ODZlMDM1IiwidHlwIjoiUmVmcmVzaCIsImF6cCI6Im9zYXBpV2ViQ2xpZW50SWQiLCJzZXNzaW9uX3N0YXRlIjoiMzM1MGY0OTMtNjYyNy00MzczLTg1NDQtZGVmZDI3YWQzYzc0Iiwic2NvcGUiOiJwcm9maWxlIGVtYWlsIn0.cDTx9BE1Df8EfGYm3VLr_MNFeymxZtJhMtlK7PVbIuk\",\"token_type\":\"bearer\",\"not-before-policy\":1586797346,\"session_state\":\"3350f493-6627-4373-8544-defd27ad3c74\",\"scope\":\"profile email\"}\n\n</code></pre> <p>The <code>access_token</code> will be used next as a Bearer.</p> <pre><code>curl http://portal.openslice.io/tmf-api/serviceCatalogManagement/v4/serviceCatalog -H 'Authorization: Bearer yJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJHZFRjQnpxczg2VW10NTRVZV8ybTJyWHJkV3dzaWdSZE9EUldMYm1memNvIn0.eyJleHAiOjE1ODgyNDA1MjQsImlhdCI6MTU4ODI0MDIyNCwianRpIjoiYjg0NGYxZDAtMzk3Mi00YTMyLThiMWEtZDAxMDY3OGZjMTQ4IiwiaXNzIjoiaHR0cDovL3BvcnRhbC5vcGVuc2xpY2UuaW8vYXV0aC9yZWFsbXMvb3BlbnNsaWNlIiwic3ViIjoiYTFhMjc2NWEtZWM4My00NDU2LWI3YjItMjA3MzE5ODZlMDM1IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoiYWRtaW4tY2xpIiwic2Vzc2lvbl9zdGF0ZSI6ImFmMmMzZmY1LTE4YWQtNDFkNC1hYTAyLTFlMGJkNzNmOTM5MSIsImFjciI6IjEiLCJzY29wZSI6InByb2ZpbGUgZW1haWwiLCJlbWFpbF92ZXJpZmllZCI6dHJ1ZSwicHJlZmVycmVkX3VzZXJuYW1lIjoiZGVtb3VzZXIifQ.SMtgV1E44_K_MQumGXZtWsLGVhYNaoM8Pk-DiFIZtUP4Zu-ervOsxHVQMX1frgVERR4jJidBcSshy9TnJ3UjF4l33WujHltbs-1UPy-gaIufVuEpl8RmbjOti3Up70vLfLXbzb6kN6WaahgobWXlbJsSXXwaBPQP6vSX5KigCa8TmzXcuqom14lOrlU-RB2zQTlJ30p7d9ag-a7o3I5m9GZWLJCZW2UYMl1JkskTHKgilA8HFQY4C9DYwWu8YDMyzqQSNumrTlURalBFidFbZvb1kp4dAyct8TysSWSbxxiwaL2RX1PWUqk-5Fpc1Q6BnBC8muMheiukFuoSkuADAg'^C\nubuntu@portal:~$ curl http://portal.openslice.io/tmf-api/serviceCatalogManagement/v4/serviceCatalog -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJHZFRjQnpxczg2VW10NTRVZV8ybTJyWHJkV3dzaWdSZE9EUldMYm1memNvIn0.eyJleHAiOjE1ODgyNDA1NzAsImlhdCI6MTU4ODI0MDI3MCwianRpIjoiOGI2ZTU0NWUtNDIyYy00NzFiLWEwN2UtYTUzYzY1NDQ0MzZmIiwiaXNzIjoiaHR0cDovL3BvcnRhbC5vcGVuc2xpY2UuaW8vYXV0aC9yZWFsbXMvb3BlbnNsaWNlIiwiYXVkIjoiYWNjb3VudCIsInN1YiI6ImExYTI3NjVhLWVjODMtNDQ1Ni1iN2IyLTIwNzMxOTg2ZTAzNSIsInR5cCI6IkJlYXJlciIsImF6cCI6Im9zYXBpV2ViQ2xpZW50SWQiLCJzZXNzaW9uX3N0YXRlIjoiMzM1MGY0OTMtNjYyNy00MzczLTg1NDQtZGVmZDI3YWQzYzc0IiwiYWNyIjoiMSIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjEzMDgyIiwiaHR0cDovL2xvY2FsaG9zdCIsImh0dHA6Ly9vcGVuc2xpY2UuaW8iLCJodHRwOi8vbG9jYWxob3N0OjEzMDAwIiwiaHR0cDovL2xvY2FsaG9zdDo0MjAwIiwiaHR0cDovL3BvcnRhbC5vcGVuc2xpY2UuaW8iXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIk5GVl9ERVZFTE9QRVIiLCJvZmZsaW5lX2FjY2VzcyIsInVtYV9hdXRob3JpemF0aW9uIiwiRVhQRVJJTUVOVEVSIiwiVVNFUiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoicHJvZmlsZSBlbWFpbCIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJkZW1vdXNlciJ9.TnzzpRLMD94UTKpT5_wkr1h4_3KUQmr4TGvFLpJ7cZx-Klrv8tB_eRkWnPqqzCAM9G21a1qXboL8MLMW8ECzG7HYKpobKOGr7LSczMOTdA2ZDyBCRUSOdW77pchu54tJ0ITEkFaDwSKMKKt04V_Sy4U-eIndj0XzzRlkDolWDnK4Z2lRaXAI6fMwOKx1Toa6RfOcemxtzl3pdtjPx92zo6MaKlbIqHK82lxdK0k8aQQaT6TmIrXbZKV2dU_1d3O0q0dVUEZJ_1kzwqOFkmxr9w0EnndC6ccYJlDAr_-GgUhhhNOn5v6tjYLUQdj5e4KEAsxIPzaCreK4un7mEAPmDw'\n\nResponse:\n\n\n[{\"uuid\":\"9e186cd5-b2b2-4a06-b1d6-895720193bc9\",\"lastUpdate\":\"2020-03-11T23:19:05Z\",\"@baseType\":\"BaseEntity\",\"@schemaLocation\":null,\"@type\":\"ServiceCatalog\",\"href\":null,\"name\":\"Example Facility Services\",\"description\":\"Example Facility Services\",\"lifecycleStatus\":\"Active\",\"version\":\"1.0\",\"validFor\":{\"endDateTime\":\"2039-11-20T23:07:21Z\",\"startDateTime\":\"2019-11-20T23:07:21Z\"},\"relatedParty\":null,\"id\":\"9e186cd5-b2b2-4a06-b1d6-895720193bc9\",\"category\":[{\"@baseType\":\"org.etsi.osl.tmf.scm633.model.ServiceCategoryRef\",\"@schemaLocation\":null,\"@type\":\"org.etsi.osl.tmf.scm633.model.ServiceCategoryRef\",\"href\":null,\"name\":\"Generic Services\",\"@referredType\":null,\"id\":\"98b9adf1-a1d6-4165-855f-153ddc2131b1\"},{\"@baseType\":\"org.etsi.osl.tmf.scm633.model.ServiceCategoryRef\",\"@schemaLocation\":null,\"@type\":\"org.etsi.osl.tmf.scm633.model.ServiceCategoryRef\",\"href\":null,\"name\":\"External\",\"@referredType\":null,\"id\":\"08ffdb3c-6237-45d0-9f3a-d43b5fc5f0b6\"},{\"@baseType\":\"org.etsi.osl.tmf.scm633.model.ServiceCategoryRef\",\"@schemaLocation\":null,\"@type\":\"org.etsi.osl.tmf.scm633.model.ServiceCategoryRef\",\"href\":null,\"name\":\"eMBB\",\"@referredType\":null,\"id\":\"ef2c90dd-b65e-4a9f-a9c3-427c9fb0219b\"}]}]\n\n\n</code></pre>"},{"location":"architecture/osom/","title":"Openslice Service Orchestration and Order Management - OSOM","text":"<p>OSOM is a service responsible for:</p> <ul> <li>Service Order Management (SOM)</li> <li>Service Orchestration (SO)</li> </ul> <p>It uses open source Flowable Business process engine (https://www.flowable.org) .</p> <p>A Service Order follows the states as defined in TMF641 specification: </p> <p></p>"},{"location":"architecture/osom/#initial-state","title":"Initial state","text":"<p>When a new order is created, it goes into the Initial state. It is stored in the repository and triggers an Event.</p> <p></p> <p>Administrators are notified usually from the Ticketing System of a new order. They login to Openslice and change the State of the order either to ACKNOWLEDGED or REJECTED. If ACKNOWLEDGED they can Propose a startDate, add Notes, and add any additional service items</p>"},{"location":"architecture/osom/#order-scheduler","title":"Order scheduler","text":"<p>A process checks every 1 minute for ACKNOWLEDGED orders.</p> <p></p> <p></p> <p>It retrieves all orders that are in ACKNOWLEDGED state and if the start date is in time it will initialize the process by settingn the order in IN_PROGRESS state. Finally the Start Order Process will start.</p>"},{"location":"architecture/osom/#start-order-process","title":"Start order process","text":"<p>This process for now is a draft simple prototype to make a simple orchestration via NFVO. Here the actual Services (TMF638/640 model) are created and attached to Service Order and Service Inventory.</p> <p></p> <p></p> <p>We expect here to check which tasks can be orchestrated by NFVO and which by human. We create the equivalent Services(TMF638/640 model) for this order.</p> <ol> <li>During check it should decide to create Service(s) for this service order O1 and send it to ServiceInventory</li> <li>The Services(TMF638 model) are assigned to the Order O1 In supportService List</li> <li>Each OrderItem OI1 is related to one serviceSpecification</li> <li>Each ServiceSpecification has also related serviceSpecRelationships</li> <li>So if we receive an order O1 for a ServiceSpec A which relates to (a bundle of) 3 specs(2 CFS, 1 RFS) we do the following:<ol> <li>Create a Service S_A(TMF638 model) for ServiceSpec A for Order O1</li> <li>We create also 3 Services S_C1, S_C2 and S_R1 equivalent to the serviceSpecRelationships (2 CFS, 1 RFS) </li> <li>At this point the order will have 1 Local Service Orchestration Process(S_A), 2 supportingServices refs(S_C1, S_C2) and 1 supportingResource(S_R1)</li> <li>The 3 supportingServices and 1 supportingResource correspond to total 4 Services in ServiceInventory</li> <li>Service S_A will have: <ol> <li>startMode 1: Automatically by the managed environment</li> <li>State: RESERVED and the Lifecycle will be handled by OSOM</li> </ol> </li> <li>Services S_C1 and S_C2 we decide that cannot be orchestrated then they have <ol> <li>startMode: 3: Manually by the Provider of the Service</li> <li>State: RESERVED and the Lifecycle will be handled by OSOM</li> <li>If the CFS is a bundle spec it is further recursively orchestrated </li> </ol> </li> <li>Service S_R1 will have <ol> <li>startMode 1: Automatically by the managed environment.</li> <li>State: RESERVED</li> <li>IF The Service has the characteristic CharacteristicByName( \"NSDID\") it will be further processed by the NFVO </li> </ol> </li> </ol> </li> </ol> <p>There will be two instances of task \"User Task Manual Complete Service\" each for Services S_C1 and S_C2. The task is Transient for now. It displays only the services that are not automated! Here is a flow for future:</p> <ol> <li>We wait here for human decision.</li> <li>From API we get a result: a. If set to ACTIVE/TERMINATED then we complete the task b. In any other state we stay in this task until it is resolved as in step a c. The Status of ORDER O1 is also updated to PARTIAL</li> </ol> <p>There will be an instance of NFVODeploymentRequest process each for Service S_R1. (see later)</p> <ol> <li>This process is related with the NFVO orchestration</li> <li>It will send a msg to NFVO(s?) for a specific deployment request</li> </ol> <p>All services in \"Order Complete\" are in a status:</p> <ol> <li>Depending on the result the service S_A is either ACTIVE or INACTIVE or TERMINATED</li> <li>The Status of ORDER O1 is also updated to COMPLETED or PARTIAL (in case we have some services running) or FAILED (in cases we have errors)</li> </ol> <p>A Service follows the states as defined in TMF638 Service Inventory specification: </p> <p></p>"},{"location":"architecture/osom/#nfvodeploymentrequest-process","title":"NFVODeploymentRequest process","text":"<p>This process is related with the NFVO orchestration It will send a msg to NFVO(s?) for a specific deployment request Then it checks the deployment status. It will wait 30 secs each time until the deployment is running (or failed)</p>"},{"location":"architecture/osom/#check-in-progress-orders-process","title":"Check In Progress orders process","text":"<p>Every 1 minute the \"Check In Progress Orders\" process is executed checking if a supported Service changed state (i.e. to ACTIVE) then the whole Order will change state (e.g. go to COMPLETED)</p> <p></p>"},{"location":"architecture/osom/#external-service-provider-deployment-request-process","title":"External Service Provider Deployment Request process","text":"<p>This process contains tasks for submitting order requests to external partners. - Submit Order To External Service Provider Task: This task creates automatically a Service Order request to a 3rd party provider SO that hosts the Service Specification - Check external service order fulfillment task: This task Check external partner for Service creations and updates our local inventory of services the service characteristics of remote Service Inventory</p>"},{"location":"architecture/osom/#fetch-partner-services-process","title":"Fetch Partner Services Process","text":"<p>Every 2 minutes the \"fetchPartnerServicesProcess\" process is executed checking remote Partner Organizations for changes in the published catalogues. The Fetch and Update External Partner Services Task is executed in paralle l for each Partner Organization </p>"},{"location":"architecture/osom/#local-service-orchestration-process","title":"Local Service Orchestration Process","text":"<p>This process handles automatically services that need to be further orchestrated or processed by OSOM. For example, for a CFS Bundled service we create such automated service instances that just aggregate the underlying services. </p>"},{"location":"architecture/tmfapi/","title":"TMF OpenAPI specification","text":"<p>PLease check the complete specification here.</p>"},{"location":"architecture/tmfapi/#api-interaction","title":"API interaction","text":""},{"location":"architecture/tmfapi/#oauth-token","title":"OAuth token","text":"<p>See oauth</p>"},{"location":"architecture/tmfapi/#request-a-protected-api-resource","title":"Request a protected API resource","text":"<p>Example: Get all Service Catalogs (check the <code>Authorization:Bearer</code> to be correct)</p> <pre><code>curl -H \"Authorization:Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX25hbWUiOiJhZG1pbiIsInNjb3BlIjpbIm9wZW5hcGkiLCJhZG1pbiIsInJlYWQiLCJ3cml0ZSJdLCJvcmdhbml6YXRpb24iOiJteW9yZ2FuaXp0aW9uIiwiZXhwIjoxNTc4NTA1MDcyLCJhdXRob3JpdGllcyI6WyJST0xFX01FTlRPUiIsIlJPTEVfQURNSU4iXSwianRpIjoiMTFlNGYxYTUtZDY0Ny00YzA1LWE0ZGMtYWFhYzUyMjk4YzMwIiwiY2xpZW50X2lkIjoib3NhcGlXZWJDbGllbnRJZE91dCJ9.gm7cKdusDrdMRkxEiFU5sENKGRC1xwVj2SgPRmE9xxx\" -H \"accept: application/json;charset=utf-8\" -X GET \"http://portal.openslice.io/tmf-api/serviceCatalogManagement/v4/serviceCatalog\"\n\n</code></pre> <p>response:</p> <pre><code>[\n {\n \"uuid\": \"9e186cd5-b2b2-4a06-b1d6-895720193bc9\",\n \"lastUpdate\": \"2019-12-19T10:45:55Z\",\n \"@baseType\": \"BaseEntity\",\n \"@schemaLocation\": null,\n \"@type\": \"ServiceCatalog\",\n \"href\": null,\n \"name\": \"Example Facility Services\",\n \"description\": \"Example Facility Services\",\n \"lifecycleStatus\": \"Active\",\n \"version\": \"1.0\",\n \"validFor\": {\n \"endDateTime\": \"2039-11-20T23:07:21Z\",\n \"startDateTime\": \"2019-11-20T23:07:21Z\"\n },\n \"relatedParty\": null,\n \"id\": \"9e186cd5-b2b2-4a06-b1d6-895720193bc9\",\n \"category\": [\n {\n \"@baseType\": \"org.etsi.osl.tmf.scm633.model.ServiceCategoryRef\",\n \"@schemaLocation\": null,\n \"@type\": \"org.etsi.osl.tmf.scm633.model.ServiceCategoryRef\",\n \"href\": null,\n \"name\": \"eMBB\",\n \"@referredType\": null,\n \"id\": \"ef2c90dd-b65e-4a9f-a9c3-427c9fb0219b\"\n },\n {\n \"@baseType\": \"org.etsi.osl.tmf.scm633.model.ServiceCategoryRef\",\n \"@schemaLocation\": null,\n \"@type\": \"org.etsi.osl.tmf.scm633.model.ServiceCategoryRef\",\n \"href\": null,\n \"name\": \"Generic Services\",\n \"@referredType\": null,\n \"id\": \"98b9adf1-a1d6-4165-855f-153ddc2131b1\"\n }\n ]\n }\n]\n</code></pre>"},{"location":"architecture/CRIDGE/CRIDGEforDevelopers/","title":"CRIDGE: A Service to manage Custom Resources in a Kubernetes Cluster","text":""},{"location":"architecture/CRIDGE/CRIDGEforDevelopers/#intended-audience-osl-developers","title":"Intended Audience: OSL developers","text":"<p>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.</p> <p>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.</p> <p>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.</p> <ol> <li> <p>CRIDGE service allows OSL to:</p> <ul> <li>Create and manage Custom Resources (CRs) using installed CRDs on a target Kubernetes cluster.</li> <li>Facilitate complex orchestration scenarios by wrapping Kubernetes APIs as TMF APIs and models.</li> <li>Handles connectivity to a Kubernetes cluster and manages the lifecycle of CRDs</li> <li>Wraps the Kubernetes API, Receives and provides resources towards other OSL services via the service bus</li> </ul> </li> <li> <p>Enabling Loose Coupling and Orchestration</p> <ul> <li>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.</li> <li>Familiar Deployment: Developers can create and deploy applications using familiar tools such as Helm charts, simplifying the process and reducing the learning curve.</li> </ul> </li> <li> <p>Ecosystem Reusability</p> <ul> <li>CRIDGE capitalizes on the extensive Kubernetes ecosystem, particularly focusing on operators (CRDs).</li> <li>Key repositories and hubs such as artifacthub.io and Operatorhub.io can be utilized for finding and deploying operators.</li> </ul> </li> <li> <p>Service Catalog Exposure and Deployment</p> <p>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.</p> </li> </ol> <p>Why the CRIDGE name? we wanted to build a service that maps TMF models to CRDs; a kind of a CRD to TMF bridge. Therefore CRIDGE was born</p>"},{"location":"architecture/CRIDGE/CRIDGEforDevelopers/#approach","title":"Approach","text":"<p>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.</p> <p>The following image illustrates the approach.</p> <p></p> <ol> <li>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</li> <li>Service Orders can be created for this service specification. The OSL Orchestrator (OSOM) will manage the lifecycle of the Service Order.</li> <li>OSOM creates a Resource in OSL Resource inventory and requests (via CRIDGE) a new Custom Resource (CR) in the target cluster<ul> <li>The resource is created in a specific namespace (for example the UUID of the Service Order)</li> <li>A CR in a cluster will be mapped in TMF model as a Resource in the resource Inventory</li> <li>Other related resources created by the CRD Controller within the namespace are automatically created in OSL Resource Inventory under the same Service Order</li> </ul> </li> </ol> <p></p> <p>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:</p> <ul> <li>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).</li> <li>Service Bus: This is the communication layer that facilitates interaction between the CRIDGE service and other OSL services.</li> <li>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.</li> <li> <p>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.</p> <p>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 :</p> </li> </ul> <pre><code> apiVersion: apiextensions.k8s.io/v1\n kind: CustomResourceDefinition\n metadata:\n name: myresource.example.com\n</code></pre> <ul> <li>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.</li> </ul> <p>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:</p> <pre><code> apiVersion: example.com/v1\n kind: Myresource\n metadata:\n name: example_resource_1\n</code></pre> <p>In a nutchell:</p> <ul> <li>Various OSL services use the Service Bus to communicate with CRIDGE.</li> <li>CRIDGE converts requests towards Kubernetes API and vice-versa, facilitating the integration of custom resources with other OSL services.</li> <li>CRDs are defined and managed through the K8s API. The example CRD is named myresource.example.com.</li> <li>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.<pre><code>> The example CRD myresource.example.com allows the creation of custom resources of type Myresource.\n> Instances of Myresource are created in various namespaces, each with unique names like example_resource_1.\n</code></pre> </li> </ul>"},{"location":"architecture/CRIDGE/CRIDGEforDevelopers/#handling-more-than-one-clusters","title":"Handling more than one clusters","text":"<p>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:</p> <p></p> <p>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</p> <p>A CRD has a globally unique name for example mycrd.example.com. So we need to somehow identify also the different cluster</p>"},{"location":"architecture/CRIDGE/CRIDGEforDevelopers/#awareness-for-crds-and-crs-in-cluster","title":"Awareness for CRDs and CRs in cluster","text":"<p>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.</p> <p>The sync process is found in the code and explained by the following picture:</p> <p></p> <p>WatcherService is executed when the cridge service application starts (see onApplicationEvent). First things:</p> <ul> <li>KubernetesClientResource is a class that wraps fabric8\u2019s KubernetesClient<ul> <li>This fabric8 KubernetesClient is initialized from the kubeconf and default context of the machine that runs CRIDGE</li> </ul> </li> <li>On CRIDGE Start up we try to register this cluster and context to OSL catalogs.<ul> <li>See registerKubernetesClientInOSLResource method which registers the KubernetesContextDefinition in Resource Inventory as a LogicalResource via createOrUpdateResourceByNameCategoryVersion method</li> </ul> </li> <li>After the creation(or update) of this cluster as a Resource in OSL we proceed to create SharedIndexInformers for CustomResourceDefinition objects</li> <li>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)</li> <li>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)<ul> <li>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</li> </ul> </li> <li>On ADD event:<ul> <li>The CRD is transformed to OSL Kubernetes domain model: method kubernetesClientResource.KubernetesCRD2OpensliceCRD</li> <li>Then the OSL Kubernetes domain model is:<ul> <li>transformed to Resource Specification and is stored to catalog (see createOrUpdateResourceSpecByNameCategoryVersion)</li> <li>Transformed to Resource and is stored to catalog (see createOrUpdateResourceByNameCategoryVersion)</li> </ul> </li> <li>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</li> <li>Then for this CRD a Watcher is added for all Resources of this Kind (fabric8\u2019s GenericKubernetesResource entity) </li> <li>When we have a newly added/updated/deleted resource of a certain CRD the method updateGenericKubernetesResourceInOSLCatalog is called for this object (fabric8\u2019s GenericKubernetesResource entity)</li> <li>We examine if the resource has label org.etsi.osl.resourceId<ul> <li>This label is added by OSOM during service orders to correlate K8S requested resources with resources in inventory</li> </ul> </li> <li>If the label exists, we update the resource by ID updateResourceById</li> <li>Else a resource is created in catalog</li> </ul> </li> </ul>"},{"location":"architecture/CRIDGE/CRIDGEforDevelopers/#deployment-of-a-new-cr-based-on-a-crd","title":"Deployment of a new CR based on a CRD","text":"<ul> <li>A message arrives to deploy a CR<ul> <li>The call examines if this CRIDGE service can handle the request (based on context and masterURL)</li> </ul> </li> <li>There are headers received and a crspec in json</li> <li>The crspec is unmarshaled as GenericKubernetesResource</li> <li>Headers are in format org.etsi.osl.*</li> <li>These headers are injected as labels <ul> <li>(see later in orchestration)</li> </ul> </li> <li>A namespace is created for this resource</li> <li>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)</li> </ul>"},{"location":"architecture/CRIDGE/CRIDGEforDevelopers/#expose-crds-as-service-specifications-in-openslice-catalogs","title":"Expose CRDs as Service Specifications in OpenSlice catalogs","text":"<p>See ExposingKubernetesResources</p>"},{"location":"architecture/CRIDGE/CRIDGEforDevelopers/#service-orchestration-and-crdscrs","title":"Service Orchestration and CRDs/CRs","text":"<p>OSOM checks the presence of attribute _CR_SPEC at the RFS to make a request for a CR deployment</p> <ul> <li>_CR_SPEC is a JSON or YAML string that is used for the request<ul> <li>It is similar to what one will do with e.g. a kubectl apply</li> <li>There are tools to translate a yaml file to a json</li> </ul> </li> </ul> <p>LCM rules can be used to change attributes of this yaml/json file, before sending this for orchestration</p> <p>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</p> <p>OSOM sends to CRIDGE a message with the following information:</p> <ul> <li>currentContextCluster: current context of cluster </li> <li>clusterMasterURL: current master url of the cluster </li> <li>org.etsi.osl.serviceId: This is the related service id that the created resource has a reference </li> <li>org.etsi.osl.resourceId: This is the related resource id that the created CR will wrap and reference. </li> <li>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 </li> <li>org.etsi.osl.serviceOrderId: the related service order id of this deployment request </li> <li>org.etsi.osl.namespace: requested namespace name </li> <li>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) </li> <li>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) </li> <li>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) </li> <li>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) </li> <li>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) </li> <li>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) </li> <li> <p>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) </p> </li> <li> <p>Parameters:</p> <ul> <li>aService reference to the service that the resource and the CR belongs to</li> <li>resourceCR reference the equivalent resource in TMF repo of the target CR. One to one mapping</li> <li>orderId related service order ID</li> <li>startDate start date of the deployment (not used currently)</li> <li>endDate end date of the deployment (not used currently)</li> <li>_CR_SPEC the spec that is sent to cridge (in json)</li> </ul> </li> <li> <p>Returns:</p> <ul> <li>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</li> </ul> </li> <li> <p>CRIDGE receives the message and creates according to the labels the necessary CR</p> </li> <li>It monitors the created resource(s) in namespace (see the Sequence Diagram in previous images)</li> <li>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</li> <li>It sends to the message bus the current resource for creation or update to the TMF service inventory</li> </ul>"},{"location":"architecture/CRIDGE/CRIDGEforDevelopers/#probe-further","title":"Probe further","text":"<ul> <li>See examples of exposing operators via OpenSlice:<ul> <li>Exposing Kubernetes Operators as a Service : Offering \"Calculator as a Service\" through OpenSlice</li> </ul> </li> </ul>"},{"location":"contributing/developing/","title":"Developing","text":"<p>OpenSlice backend services are mainly implemented with Java 17 or above and Spring boot.</p> <p>OpenSlice uses various subsystems and depending on the module would you like to work, other subsystems must be present (you can disable them though in the code, e.g. at docker-compose.yaml file).</p> <p>To get the latest development branch:</p> <pre><code>wget https://labs.etsi.org/rep/osl/code/org.etsi.osl.main/-/raw/develop/compose/deploy.sh \nsudo ./deploy.sh develop #[or replace develop with other branch name]\n</code></pre> <p>You may follow the installation process, as described at \"develop\" tagged documentation.</p> <p>To work on a specific subsystem e.g. org.etsi.osl.tmf.api, you must:</p> <p>1a - Deploy only the core necessary subsystems through:</p> <pre><code>sudo docker compose --profile dev down;sudo docker compose --profile dev up -d --build\n</code></pre> <p>Note --profile dev that will only deploy the core dependency subsystems, instead of the whole OpenSlice.</p> <p>1b - Or alternatively, commend out the respective container from the docker-compose.yaml file, so as to deploy the whole OpenSlice, except the subsystem you want to work on, following the provided installation steps.</p> <p>2 - Clone the respective repository, e.g. https://labs.etsi.org/rep/osl/code/org.etsi.osl.tmf.api/-/tree/develop</p> <p>3 - Code :)</p>"},{"location":"contributing/developing/#general-requirements","title":"General requirements","text":"<ul> <li>Docker should be installed in your development environment</li> <li>Run the core subsystems (see above section)</li> </ul>"},{"location":"contributing/developing/#slack","title":"Slack","text":"<p>Feel free to join OpenSlice Slack for any development oriented questions.</p>"},{"location":"contributing/developing/#examples-of-developing-on-specific-subsystems","title":"Examples of developing on specific subsystems","text":""},{"location":"contributing/developing/#vnfnsd-catalog-management-and-nsd-deployment-api-service","title":"VNF/NSD Catalog Management and NSD Deployment API service","text":"<p>Clone the repository: https://labs.etsi.org/rep/osl/code/org.etsi.osl.portal.api/-/tree/develop</p> <p>Check the docker-compose.yml file. Default port is 13080. Check specifically the datasource username/password, server port.</p> <p>Make sure that the core subsystems are up and running.</p> <p>Execute it with </p> <pre><code>mvn spring-boot:run\n</code></pre> <p>For verification, Swagger API of the service is at <code>http://localhost:13000/osapi/swagger-ui/index.html</code>. </p> <p>There, you may try there various REST actions and authenticate via the OAuth server without the use of the UI.</p>"},{"location":"contributing/developing/#vnfnsd-catalog-management-and-nsd-deployment-web-ui-service","title":"VNF/NSD Catalog Management and NSD Deployment WEB UI service","text":"<p>The Web UI is written in AngularJS.</p> <p>Clone the repository: https://labs.etsi.org/rep/osl/code/org.etsi.osl.portal.web/-/tree/develop</p> <p>By default the project org.etsi.osl.portal.api exposes the folder ../org.etsi.osl.portal.web/src/ in a folder testweb (Check class MvcConfig.java in org.etsi.osl.portal.api) for development. (In production nginx is used). Point your browser to <code>http://localhost:13000/osapi/testweb/index.html/</code></p>"},{"location":"contributing/developing/#versionrelease-management","title":"Version/release management","text":"<p>Check this nice article on how we develop and release versions.</p> <p>https://nvie.com/posts/a-successful-git-branching-model/</p> <p>We develop in the develop branch and follow a issue driven development model.</p>"},{"location":"contributing/developing/#wishlist","title":"Wishlist","text":"<p>Check also our wishlist of new features. You can add your own.</p> <p>See Wishlist.</p>"},{"location":"contributing/wishlist/","title":"TMF API","text":"<ul> <li>RBAC of API endpoints</li> <li>TMF Ticketing API support</li> <li>TMF Product</li> <li>HATEOAS integration</li> <li>Select Specs that can be exposed to partners (maybe with a characteristic?)</li> </ul>"},{"location":"contributing/wishlist/#resource-management","title":"resource management","text":"<ul> <li>Resource Activation and Configuration API TMF702 (NEW) (https://projects.tmforum.org/wiki/pages/viewpage.action?pageId=128855518)</li> </ul>"},{"location":"contributing/wishlist/#tmf-web","title":"TMF WEB","text":""},{"location":"contributing/wishlist/#osom","title":"OSOM","text":"<ul> <li>Actions on service order item and acknowledge order status will define the lifecycle</li> <li>action shutdown on specific date for service order</li> <li>action edit on service order item</li> </ul>"},{"location":"contributing/wishlist/#dynamic-attribute-transformation","title":"Dynamic attribute transformation","text":"<ul> <li>DTM decision tables support per Service Specification</li> <li>Schedule Termination of completed order on running services</li> </ul>"},{"location":"contributing/wishlist/#nfvo-connectivity","title":"NFVO connectivity","text":""},{"location":"contributing/wishlist/#osm-client","title":"OSM Client","text":"<ul> <li>VNF/NSD config params Day 2</li> <li>NSD Lifcecylce</li> <li>NST support</li> </ul>"},{"location":"contributing/wishlist/#nfv-api","title":"NFV API","text":""},{"location":"contributing/wishlist/#nfv-web","title":"NFV WEB","text":""},{"location":"contributing/wishlist/#3rd-party-connectivity","title":"3rd party connectivity","text":""},{"location":"contributing/wishlist/#flowone-connector","title":"FlowOne connector","text":""},{"location":"contributing/wishlist/#openstack-connector","title":"Openstack connector","text":""},{"location":"contributing/wishlist/#kubernetes-connector","title":"Kubernetes connector","text":""},{"location":"contributing/wishlist/#centrallog","title":"CentralLog","text":"<ul> <li>Events from TMF to be written to Central Log</li> </ul>"},{"location":"contributing/wishlist/#authentication","title":"Authentication","text":""},{"location":"naas/exposed_apis/","title":"Supported TMFORUM exposed APIs","text":"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"},{"location":"naas/gst_to_tmf/","title":"Generic Slice Template as a Service Specification","text":""},{"location":"naas/gst_to_tmf/#intended-audience-service-designers","title":"Intended Audience: Service Designers","text":"<p>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</p> <p>Moreove it Proposes standardized Network Slice Templates (NESTs) to target specific use cases</p> <p>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.</p> <p>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.</p> <p></p> <p>The GST to TM Forum via OpenSlice:</p> <pre><code> * 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.\n * TMF Service Specification: Demonstrates the transformation of GST attributes into a TM Forum service specification, showing JSON code snippets that define service parameters.\n * 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.\n</code></pre> <p>What was our flow:</p> <pre><code>* Started with defining service requirements and attributes using GST.\n* Translated these GST attributes into a formal TM Forum service specification.\n* 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.\n</code></pre>"},{"location":"naas/gst_to_tmf/#probe-further","title":"Probe further","text":"<p>See v9 of the GST model in GSMA here</p>"},{"location":"naas/introduction/","title":"Network as a Service (NaaS)","text":"<p>This section describes some core concepts for Delivering Network as a Service in OpenSlice. There are many articles and reports on the subject like:</p> <ul> <li>TMF909 API Suite Specification for NaaS</li> <li>TMF926A Connectivity_as_a_Service </li> <li>TMF931-Open_Gateway_Onboarding_and_Ordering_Component_Suite</li> <li>GSMA Open Gatewy initiative</li> </ul> <p>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.</p>"},{"location":"naas/introduction/#openslice-and-naas","title":"OpenSlice and NaaS","text":"<p>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.</p> <p>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.</p>"},{"location":"naas/introduction/#probe-further","title":"Probe further","text":"<ul> <li>For a complete list of supported APIs, see Supported APIs</li> <li>Check the defined user roles of OpenSlice in our Terminology</li> </ul>"},{"location":"naas/lcm_intro/","title":"Lifecycle Management - LCM","text":"<p>Lifecycle Management: The orchestration framework handles the activation, termination and any necessary modifications throughout the service lifecycle.</p>"},{"location":"naas/lcm_intro/#intended-audience-service-designers","title":"Intended Audience: Service Designers","text":"<p>In OpenSlice the Lifecycle of a service follows in general the concept of Network Slice lifecycle as defined by 3GPP.</p> <p></p>"},{"location":"naas/lcm_intro/#introduction-in-openslice-lcm","title":"Introduction in OpenSlice LCM","text":"<p>OpenSlice adopted the LCM model by 3GPP and mapped to the TMF model service state. Next we discuss briefly the process and the relationships.</p> <p>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. </p> <p>Here is an overview of these stages and relationships with OpenSlice:</p>"},{"location":"naas/lcm_intro/#0-preparation-phase","title":"0. Preparation Phase","text":"<p>This phase is performed by Service Designers</p>"},{"location":"naas/lcm_intro/#service-design","title":"Service Design:","text":"<ul> <li>Requirements Gathering: Collect service requirements from stakeholders, including performance metrics, quality of service (QoS), security needs, and geographical coverage.</li> <li>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).</li> <li>Resource Planning: Identify and plan the required resources, including network functions, computing power, storage, and connectivity, inclluding network function configurations.</li> <li>Expose to Service Catalog: Expose to service catalog for user ordering.</li> </ul> <p>Next phases are handled by the Service Orchestrator after a service is scheduled for instantiation</p> <p>If it is a bundle of services, each services follows its own Lifecycle!</p>"},{"location":"naas/lcm_intro/#1-instantiation-phase","title":"1. Instantiation Phase","text":""},{"location":"naas/lcm_intro/#service-instantiation","title":"Service Instantiation:","text":"<ul> <li>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.</li> <li>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)</li> <li>OpenSlice Service Orchestrator creates the services at \"RESERVED\" state</li> <li>User Notification: There could be an email notification from the system (if Bugzilla is configured)</li> </ul>"},{"location":"naas/lcm_intro/#service-deployment","title":"Service Deployment:","text":"<ul> <li>Activation: OpenSlice Service Orchestrator activates the network service and makes the service available to the end-users. This may involve:</li> <li>Create any related services that the service depends on</li> <li>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)</li> <li>Scheduling instantiation, Resolving dependencies and passing paramemters between controllers,</li> <li>setting up user accounts, provisioning access credentials -this is performed either offline or via other services.</li> <li>OpenSlice Service Orchestrator if everything is succesful puts the service at \"ACTIVE\" state</li> <li>User Notification: There could be an email notification from the system (if Bugzilla is configured)</li> </ul>"},{"location":"naas/lcm_intro/#2-operation-phase","title":"2. Operation Phase","text":""},{"location":"naas/lcm_intro/#service-operation","title":"Service Operation:","text":"<ul> <li>Lifecycle Management: Manage the network slice throughout its lifecycle, including scaling, reconfiguration, and adaptation to changing requirements. </li> <li>In OpenSlice this is performed with Lifecycle management Rules (see next)</li> </ul> <p>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:</p> <ul> <li>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.</li> <li>Maintenance: Conduct regular maintenance activities, including software updates, patching, and optimization to ensure the service runs smoothly.</li> <li>Scaling: Dynamically scale the resources up or down based on the demand and performance requirements.</li> <li>Fault Management: Detect and resolve faults in the network slice to minimize downtime and maintain service quality.</li> </ul>"},{"location":"naas/lcm_intro/#3-decommissioning-phase","title":"3. Decommissioning Phase","text":"<ul> <li>Service Termination: Service Orchestrator terminates the network service. This may involve:</li> <li>Terminate any related services that the service depends on</li> <li>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)</li> <li>Scheduling termination, Resolving dependencies and passing paramemters between controllers</li> <li>OpenSlice Service Orchestrator, if everything is succesful, puts the service at \"TERMINATED\" state</li> <li>User Notification: There could be an email notification from the system (if Bugzilla is configured)</li> </ul>"},{"location":"naas/lcm_intro/#high-level-example-enhanced-mobile-broadband-embb-service-lifecycle","title":"High level example: Enhanced Mobile Broadband (eMBB) Service Lifecycle","text":"<ol> <li> <p>Preparation:</p> </li> <li> <p>Define eMBB service requirements for high bandwidth and low latency.</p> </li> <li>Create an eMBB service specification template specifying related services and resources to Kubernetes Operators, VNFs for content delivery and traffic management.</li> <li> <p>Expose to catalog</p> </li> <li> <p>Instantiation:</p> </li> <li> <p>Instantiate other services and allocate resources such as edge computing nodes and high-capacity links.</p> </li> <li> <p>Configure the service to prioritize video streaming traffic.</p> </li> <li> <p>Operation:</p> </li> <li> <p>Monitor the service to ensure it meets high-bandwidth requirements.</p> </li> <li> <p>Scale up resources during peak usage periods, such as live sports events.</p> </li> <li> <p>Decommissioning:</p> </li> <li> <p>Notify users about service termination.</p> </li> <li>Decommission the network service, reclaiming resources for other services.</li> </ol>"},{"location":"naas/lcm_intro/#probe-further","title":"Probe further","text":"<ul> <li>See 3GPP Lifecycle</li> </ul>"},{"location":"naas/lcm_rules_intro/","title":"Lifecycle Management Rules - LCM Rules","text":"<p>Lifecycle Management Rules: Defining complex conditions and actions during the lifecycle of a service and any necessary modifications throughout the service lifecycle.</p>"},{"location":"naas/lcm_rules_intro/#intended-audience-service-designers","title":"Intended Audience: Service Designers","text":"<p>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)</p> <p>So in the system there are already predefined recipes, which in each process-step of the workflow some piece of code is executed. </p> <p>How is it possible to intervene in the workflow process and inject some user defined actions? The next image illustrates the idea</p> <p></p> <p>## How is it possible to intervene in the workflow process and affect it?</p> <p>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:</p> <ul> <li>PRE_PROVISION</li> <li>CREATION</li> <li>AFTER_ACTIVATION </li> <li>SUPERVISION </li> <li>AFTER_DEACTIVATION </li> </ul> <p>The following figure displays the different phases that the rules are performed, during the lifecycle of a Network Service Instance. </p> <p></p> <ul> <li>PRE_PROVISION rules: Run only once just before creating a service with a given priority. </li> <li>CREATION rules: Run while the referenced service dependencies of a service are created</li> <li>AFTER_ACTIVATION rules: Run only once just after a service get the ACTIVE state</li> <li>SUPERVISION rules: Run when a characteristic of a service is changed and the service is in the ACTIVE state </li> <li>AFTER_DEACTIVATION rules: Run only once just after a service get the INACTIVE/TERMINATED state </li> </ul> <p>In general the rules allow to perform many actions during service LCM. These are some examples:</p> <ul> <li>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</li> <li>Translate GST/NEST parameter values to other values passed later to NFVO for instantiation or control</li> <li>Define complex OSM Configs based on other dependencies and passing variables</li> <li>Define any dependencies when creating the referenced services</li> <li>Dynamically include new service dependencies</li> <li>Create new service orders so include dynamically other services</li> <li>Call external (RESTful) services (via http(s), define payload, examine response)</li> </ul>"},{"location":"naas/lcm_rules_intro/#examine-if-the-rules-are-executed-successfully","title":"Examine if the rules are executed successfully","text":"<p>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.</p>"},{"location":"naas/lcm_rules_intro/#probe-further","title":"Probe further","text":"<ul> <li>In the Service Design section we present in details the Lifecycle rules and how one can design them</li> <li>Many of them are used in our provided Service Design examples</li> </ul>"},{"location":"naas/resource_catalog/","title":"OpenSlice Resource Catalog:","text":"<pre><code>* Resource Specifications: Defines the underlying resources required to deliver services, such as network components, servers, and software.\n* Resource Availability: Tracks the availability and status of resources to ensure efficient service delivery.\n</code></pre>"},{"location":"naas/service_catalog/","title":"OpenSlice Service Catalogs","text":"<p>OpenSlice offers complete management of Service Catalogs.</p>"},{"location":"naas/service_catalog/#intended-audience-service-designers-openslice-administrators-users","title":"Intended Audience: Service Designers, OpenSlice administrators, Users","text":"<p>OpenSlice offers complete management of Service Catalogs which offer to end users:</p> <ul> <li>Service categories: Lists the available services, including their specifications and performance metrics.</li> <li>Service Bundles: Combines multiple services into a single offering to provide added value to customers.</li> </ul> <p>Service Catalogs contain Service Specifications (organized in Service Categories) exposed to users for Service Orders.</p>"},{"location":"naas/service_catalog/#ui-management","title":"UI management","text":"<p>In the UI this looks like the following. Service catalogs and categories exposed in Service marketplace. </p> <p>In the menu the administrator can manage the Service Catalogs and Categories.</p> <p></p>"},{"location":"naas/service_catalog/#api-exposed","title":"API exposed","text":"<p>When installing OpenSlice the API endpoints can be browsed at: </p> <pre><code>[YOURDOMAIN]/tmf-api/swagger-ui/index.html?urls.primaryName=tmf-api-633-ServiceCatalogManagement-v4.0.0\n\nendpoint examples:\n\n/serviceCatalogManagement/v4/serviceCatalog List or find ServiceCatalog objects\n/serviceCatalogManagement/v4/serviceCategory List or find ServiceCategory objects\n\n</code></pre>"},{"location":"naas/service_catalog/#example-use-case","title":"Example Use Case","text":"<p>Scenario: A service provider wants to offer a new managed XXXX service to enterprise customers.</p> <ul> <li>Service Definition: Service Template thus create a template for the XXXX service, including specifications for bandwidth, network features, and performance metrics.</li> <li>Service Catalog Integration: Add to Service Catalog the XXXX service with all relevant details.</li> <li>Service Delivery/Order: Provision Service by Using the orchestration system to provision and configure the XXXX service based on customer orders.</li> </ul>"},{"location":"naas/service_catalog/#probe-further","title":"Probe further","text":"<ul> <li>Read the model of Service Catalogs in TMF TMF633 Service Catalog API User Guide v4.0.0</li> <li>Check a demo of the API here</li> <li>Check a demo of the Catalog and Categories here</li> </ul>"},{"location":"naas/service_inventory/","title":"Service Inventory","text":"<p>Service Inventory contains refences to running services that realize a Service Order</p>"},{"location":"naas/service_inventory/#intended-audience-service-designers-openslice-administrators-users","title":"Intended Audience: Service Designers, OpenSlice administrators, Users","text":"<p>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. </p> <p>This inventory enables real-time visibility into the status, configuration, and dependencies of each service, facilitating effective management, troubleshooting, and optimization. </p> <p>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 inital requst. </p>"},{"location":"naas/service_inventory/#ui-management","title":"UI management","text":"<p>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.</p>"},{"location":"naas/service_inventory/#api-exposed","title":"API exposed","text":"<p>When installing OpenSlice the API endpoints can be browsed at: </p> <pre><code>[YOURDOMAIN]/tmf-api/swagger-ui/index.html?urls.primaryName=tmf-api-638-ServiceInventoryManagement-v4.0.0\n</code></pre> <p>endpoint examples:</p> <p>/serviceInventory/v4/service List or find Service objects</p>"},{"location":"naas/service_inventory/#probe-further","title":"Probe further","text":"<ul> <li>See Ordering Services from catalogs</li> <li>See Service Design</li> </ul>"},{"location":"naas/service_ordering/","title":"Service Ordering","text":"<p>Customer Facing Service Specifications - or also CFSSpec (organized in Service Categories) are exposed to users for Service Orders.</p>"},{"location":"naas/service_ordering/#intended-audience-service-designers-openslice-administrators","title":"Intended Audience: Service Designers, OpenSlice administrators","text":"<p>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 bunlde), 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.</p> <p>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. </p> <p>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.</p> <p>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.</p> <p>Ongoing monitoring and other actions can be performed by the Life Cycle management rules</p> <p>Future developments: In future releases it might be possible the ongoing monitoring and support provided to ensure continuous performance and reliability. The service could undergoe a series of tests to ensure it meets the specified performance metrics and SLAs before delivering</p>"},{"location":"naas/service_ordering/#ui-management","title":"UI management","text":"<p>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.</p>"},{"location":"naas/service_ordering/#api-exposed","title":"API exposed","text":"<p>When installing OpenSlice the API endpoints can be browsed at: </p> <pre><code>[YOURDOMAIN]/tmf-api/swagger-ui/index.html?urls.primaryName=tmf-api-641-ServiceOrdering-v4.0.0\n</code></pre> <p>endpoint examples:</p> <p>/serviceOrdering/v4/serviceOrder List or find ServiceOrder objects</p>"},{"location":"naas/service_ordering/#probe-further","title":"Probe further","text":"<ul> <li>See Ordering Services from catalogs</li> <li>See Service Design</li> </ul>"},{"location":"naas/service_spec/","title":"OpenSlice Service Specification","text":"<p>OpenSlice offers complete management of Service Specifications.</p>"},{"location":"naas/service_spec/#intended-audience-service-designers","title":"Intended Audience: Service Designers","text":"<p>Service Specification is an entity that describes a service offering. There are two types of Service Specifications:</p> <ul> <li>Resource Facing Service Specification</li> <li>Customer Facing Service Specification</li> </ul>"},{"location":"naas/service_spec/#resource-facing-service-specification","title":"Resource Facing Service Specification","text":"<p>Is a Service that It exposes a resource Specification as a Service. (For example expose a Network Service Descriptor as a Service)</p>"},{"location":"naas/service_spec/#customer-facing-service-specification","title":"Customer Facing Service Specification","text":"<p>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</p>"},{"location":"naas/service_spec/#definition","title":"Definition","text":"<p>Usually a Service Specification has the following aspects:</p> <ul> <li>Name, Description, Version</li> <li>Marked as a Service Bundle: Combines multiple services into a single offering to provide added value to customers.</li> <li>if is is a Bundle then you must add Related Service Specifications</li> <li>If it is a Resource Facing Service Specification has multiple related Resource Facing Service Specifications</li> <li>Characteristics: a list of service characteristics and their type (TEXT, INTEGER, etc)</li> <li>Also they can be exposed as \"Configurable\" so to allow to end-users during the Service Order to select or type values</li> <li>A logo, displayed if needed in the Service Marketplace</li> <li>Any attachments that further help the user</li> <li>Life Cycle Rules that determine the behavior of the Service and instrument the Service Orchestrator. More on Life Cycle Rules here</li> </ul> <p>Service Designers can create a Service Specification from scratch or use some templates:</p> <pre><code>* Create a Service based from a Network Service Descriptor (NSD)\n* Create a Service based on a Kubernetes Operator\n* Create a Service based on the GSMA GST - Generic Slice Template\n</code></pre>"},{"location":"naas/service_spec/#ui-management","title":"UI management","text":"<p>In the UI this looks like the following.</p> <p>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.</p>"},{"location":"naas/service_spec/#api-exposed","title":"API exposed","text":"<p>When installing OpenSlice the API endpoints can be browsed at: </p> <pre><code>[YOURDOMAIN]/tmf-api/swagger-ui/index.html?urls.primaryName=tmf-api-633-ServiceCatalogManagement-v4.0.0\n</code></pre> <p>endpoint examples:</p> <p>/serviceCatalogManagement/v4/serviceSpecification List or find ServiceSpecification objects</p>"},{"location":"naas/service_spec/#example-use-case","title":"Example Use Case","text":"<p>Scenario: A service provider wants to offer a new managed XXXX service to enterprise customers.</p> <ul> <li>Service Definition: Create a service specification template for the XXXX service, including specifications for bandwidth, network features, and performance metrics.</li> </ul>"},{"location":"naas/service_spec/#probe-further","title":"Probe further","text":"<ul> <li>Read the model of Service Catalogs in TMF TMF633 Service Catalog API User Guide v4.0.0</li> <li>Check a demo of the API here</li> <li>Check a demo of the Service Specifications in Catalog and Categories here (You need to login - see main guide page)</li> <li>Check the GSMA GST</li> </ul>"},{"location":"naas/so_intro/","title":"Service Orchestration","text":"<ul> <li>Service Orchestration: 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.</li> </ul>"},{"location":"naas/so_intro/#intended-audience-service-designers","title":"Intended Audience: Service Designers","text":"<p>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.</p> <p>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)</p> <p></p> <p>This section provides a high level overview of the Service Orchestration process.</p>"},{"location":"naas/so_servicespec_to_services_nfv/","title":"From Service Specification to NFV based services","text":"<p>After a Service Order completion, active services with their additional characteristics are found:</p> <ul> <li>From the Order Items of a selected Service order</li> <li>from the menu of Service inventory and then selecting details of each service</li> <li>through the Service Inventory API (TMF 638 - Service Inventory Management ) </li> </ul> <p>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. </p> <p></p> <p>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</p>"},{"location":"naas/so_servicespec_to_services_nfv/#interacting-with-an-active-service-day-2-config","title":"Interacting with an Active Service (Day 2 config)","text":"<p>In some cases, if the underlying service is configured with actions (for example in OSM Day 2 primitive actions), there are characteristics that can be modified. Usually they are named like : ::Primitive:: <p>The user can edit the characteristic with a new value. The value is propagated through the OSOM and NFVO down to the related VNF.</p>"},{"location":"naas/so_servicespec_to_services_nfv/#terminatinginactivating-a-service","title":"Terminating/Inactivating a service","text":"<p>You can terminate the service with one of the following processes:</p> <ul> <li>Select the related Service Order and terminate the Order Item. This will delete all the underlying related active services. The Order goes to ACKNOWLEDGED->INPROGRESS->COMPLETE</li> <li>To terminate or inactivate a service, select the specific service from the inventory, press Edit and set the State either to Inactive or Terminated</li> </ul> <p>Warning: if you terminate or inactivate a service the action cannot be undone. </p>"},{"location":"naas/so_servicespec_to_services_nfv/#uml-sequence-diagram","title":"uml: sequence diagram","text":"<p>Here I will embed PlantUML markup to generate a sequence diagram.</p> <p>I can include as many plantuml segments as I want in my Markdown, and the diagrams can be of any type supported by PlantUML.</p>"},{"location":"naas/nfv/nfvservices/","title":"NFV Services","text":"<p>NFV Services are managed through a dedicate UI the NFV portal (eg http://portal.openslice.io/nfvportal)</p> <p>Users are able through this portal to manage their NFV artifacts towards the NFVO, ( for example onboard VNFs and NSDs to a target OSM)</p> <p>Openslice NFV Services target to accommodate the following envisaged user roles. All users are assumed to be Authenticated:</p> <ul> <li>NFV developer: This role is responsible to upload VNF and NSD Descriptors in the Openslice services towards NFVO like OSM</li> <li>Services administrator: This role represents the user that are responsible for maintenance of the Openslice services</li> </ul> <p>(obsolete: )</p> <ul> <li>Testbed provider: This role represents users that are responsible for testbed administration, configuration, integration, adaptation, support, etc</li> <li>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)</li> </ul> <p>Finally an anonymous user role exists who has some really simple usage scenarios (e.g. signup through the portal)</p> <p>During the onboarding process the following occurs:</p> <p>\u2022 A NFV developer submits a NFV archive (VNF or NSD) (he can later manage if needed some metadata) \u2022 The administrator can manage the NFV artifact (e.g. edit it) \u2022 The administrator On-Boards the NFV artifact to the target MANO \u2022 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</p>"},{"location":"naas/nfv/nfvservices/#request-a-new-nsd-deployment-this-is-different-in-comparison-to-services","title":"Request a new NSD deployment (this is different in comparison to Services)","text":"<p>A developer requests a new network service deployment (which NSD, tentative dates, target infrastructure, etc.). The request is marked as UNDER_REVIEW</p> <ul> <li>The administrator is notified about the new request and he has the following options:</li> <li>Schedule the deployment for the requested dates or propose other dates. The request is marked as SCHEDULED</li> <li>Reject the request for some reason. The Request is marked as REJECTED</li> <li>Deploy the request to target VIM(s). The Request is marked as RUNNING</li> <li>Finalize the deployment and release resources. The Request is marked as COMPLETED</li> <li>every change of the request-lifecycle the experimenter is notified.</li> </ul>"},{"location":"service_design/catalogs/","title":"Catalogs and Templates","text":"<p>The Openslice Service Catalogue (accessible through the API or Services portal) contains the representation of Service Specifications, either created from the provider defining service attributes, or by supporting the GSMA Generic Slice Templates (GST) as well as the VINNI Service Blueprint. The following scenarios are supported by the Openslice Service Catalogue.</p>"},{"location":"service_design/catalogs/#createdesign-a-service-specification","title":"Create/Design a Service Specification","text":""},{"location":"service_design/catalogs/#first-import-some-resources-as-resource-facing-services-rfss","title":"First Import some Resources as Resource Facing Services (RFSs)","text":"<p>If you have any NSDs as NFV artifacts, import them through the UI menu (Import from NSD list). Then an NSD is imported as a resource and an RFS automatically is created. RFSs then later are used to design a Customer Facing Service Specification</p>"},{"location":"service_design/catalogs/#createdesign-a-customer-facing-service-specification","title":"Create/Design a Customer Facing Service Specification","text":"<p>Customer Facing Service Specification are the services offered to customers. You can create a new Service Specification from the menu. The services created through the UI are Customer Facing Services (CFS). Usually you create a CFS as a bundle and then you include Service Specification Relationships with RFSs or/and CFSs.</p> <p>Any Service Specification Characteristics from the RFS are copied to the CFS specification. A CFS can include multiple RFS or/and CFSs. For example you can create a CFS spec called \"A 5G Service\" which is a bundle of two other services (include them in Service Specification Relationships) such as 5G eMBB Slice and a Customer VPN. So when the user orders \"A 5G Service\" services from 5G eMBB Slice and a Customer VPN will be created during the order.</p>"},{"location":"service_design/catalogs/#initial-configuration-for-osm-deployment","title":"Initial configuration for OSM deployment","text":"<p>if you have an initial configuration that needs to be applied in the NSD deployment, then you go to the RFS (or CFS) and in Service Specification Characteristics go and edit the OSM_CONFIG characteristic. You can add in the Service Characteristic Value, in the Value field something like the following example which gives a floating IP to a VNF:</p> <pre><code>{ \"nsdId\": \"e855be91-567b-45cf-9f86-18653e7ea\", \"vimAccountId\": \"4efd8bf4-5292-4634-87b7-7b3d49108\" , \"vnf\": [ {\"member-vnf-index\": \"1\", \"vdu\": [ {\"id\": \"MyCharmedVNF-VM\", \"interface\": [{\"name\": \"eth0\", \"floating-ip-required\": true }]}]}]}\n\n</code></pre> <p>or a more complex example (beautify it first if you want to view it, but in the parameter OSM_CONFIG must be minified like the example):</p> <pre><code>{\"nsdId\":\"e855be91-567b-45cf-9f86-18653e7\",\"vimAccountId\":\"4efd8bf4-5292-4634-87b7-7b3d491\",\"vnf\":[{\"member-vnf-index\":\"1\",\"vdu\":[{\"id\":\"haproxy_vdu\",\"interface\":[{\"name\":\"haproxy_vdu_eth1\",\"floating-ip-required\":true}]}]}],\"vld\":[{\"name\":\"pub_net\",\"vim-network-name\":\"OSMFIVE_selfservice01\"},{\"name\":\"management\",\"vim-network-name\":\"OSMFIVE_selfservice01\"},{\"name\":\"lba_net\",\"vim-network-name\":\"lba_net\",\"vnfd-connection-point-ref\":[{\"member-vnf-index-ref\":\"1\",\"vnfd-connection-point-ref\":\"haproxy_private\",\"ip-address\":\"192.168.28.2\"}]},{\"name\":\"backend_net\",\"vim-network-name\":\"backend_net\",\"vnfd-connection-point-ref\":[{\"member-vnf-index-ref\":\"3\",\"vnfd-connection-point-ref\":\"haproxy_public\",\"ip-address\":\"192.168.20.2\"}]},{\"name\":\"lb_sb_net\",\"vim-network-name\":\"lb_sb_net\",\"vnfd-connection-point-ref\":[{\"member-vnf-index-ref\":\"3\",\"vnfd-connection-point-ref\":\"haproxy_private\",\"ip-address\":\"192.168.28.2\"}]},{\"name\":\"breaking_point_Spain\",\"vim-network-name\":\"sb_repo_net\"},{\"name\":\"breaking_point_Greece\",\"vim-network-name\":\"5TONICexternal\"}],\"additionalParamsForVnf\":[{\"member-vnf-index\":\"2\",\"additionalParams\":{\"target_IP\":\"192.168.20.2\"}},{\"member-vnf-index\":\"4\",\"additionalParams\":{\"target1_IP\":\"192.168.21.2\",\"target2_IP\":\"10.154.252.10\"}}]}\n</code></pre> <p>You can leave the Alias and Unit of Measure as is. Check also the is Default.</p>"},{"location":"service_design/catalogs/#day-2-primitive-actions","title":"Day 2 Primitive Actions","text":"<p>NFVOs like OSM allow to perform actions while a service is running, for example change attributes or make actions on a specific VNF. To design this do something similar to the following example:</p> <ul> <li>Go to the RFS related to the NSD that contains VNFs with primitives</li> <li>create a characteristic named Primitive:: , e.g. Primitive::touch <li>select Value Type: ARRAY</li> <li>add Service Characteristic Value: i) alias=primitive, value= (e.g. touch), ii) alias=member_vnf_index, value= (e.g. 1), iii) add the params that the user will change in alias the name of param and in value an initial value (e.g. alias=filename, value=myfile.txt) <p>In the above example, when the service is running and the user goes to service inventory to MODIFY it, changes the value of the alias=filename, value=myfile.txt, to value =secondfile.txt. Then inside the VNF a file will be created called secondfile.txt</p>"},{"location":"service_design/catalogs/#generic-slice-templates-gst","title":"Generic Slice Templates (GST)","text":"<p>(Offered only as a design for now. THere is no direct implementation to NFV) On October 16th 2019 GSMA published NG.116 Version 2.0 which defines the Generic Network Slice Template (GST). GST is a set of attributes that can characterise a type of network slice/service. GST is generic and is not tied to any specific network deployment. Here is a list of the various attributes of the template:</p> <ul> <li>Availability</li> <li>Area of Service</li> <li>Delay tolerance</li> <li>Deterministic communication</li> <li>Downlink throughput per network slice</li> <li>Downlink throughput per UE</li> <li>Energy efficiency</li> <li>Group communication support</li> <li>Isolation level</li> <li>Location based message delivery</li> <li>Maximum supported packet size</li> <li>Mission critical support</li> <li>MMTel support</li> <li>NB-IoT support</li> <li>Network Slice Customer network functions</li> <li>Number of connections</li> <li>Number of terminals</li> <li>Performance monitoring</li> <li>Performance prediction</li> <li>Positioning support</li> <li>Radio spectrum</li> <li>Reliability</li> <li>Root cause investigation</li> <li>Session and Service Continuity support </li> <li>Simultaneous use of the network slice</li> <li>Slice quality of service parameters</li> <li>Support for non-IP traffic </li> <li>Supported access technologies </li> <li>Supported device velocity </li> <li>Synchronicity</li> <li>Terminal density </li> <li>Uplink throughput per network slice </li> <li>Uplink throughput per UE</li> <li>User management openness</li> <li>User data access </li> <li>V2X communication mode</li> </ul> <p>Openslice offers the GST in a format that is machine readable and aligned with the TMF SID model. Here is a tentative approach in JSON : https://github.com/openslice/org.etsi.osl.tmf.api/blob/master/src/main/resources/gst.json</p> <p>Providers can clone a GST as e NEST directly in Openslice Web portal and the adjust the default attributes to their Service Specification</p>"},{"location":"service_design/catalogs/#manage-a-service-specification","title":"Manage a Service Specification","text":"<p>You can manage them though the Web UI</p>"},{"location":"service_design/catalogs/#assign-a-service-specification-to-service-categories-and-publish","title":"Assign a Service Specification to Service Categories and Publish","text":"<p>Just create categories and from the menu select the category and add services</p>"},{"location":"service_design/catalogs/#retireremove-a-service-specification","title":"Retire/Remove a Service Specification","text":"<p>Delete it from the category</p>"},{"location":"service_design/catalogs/#consume-and-expose-service-specifications-from-other-service-catalogues","title":"Consume and expose Service Specifications from other Service Catalogues","text":"<p>See more on Consuming Services From External Partner Organizations</p>"},{"location":"service_design/intro/","title":"Service Design in OpenSlice","text":"<p>This section offers details on how to design Service Specifications and expose them in Service Catalogs</p>"},{"location":"service_design/intro/#intended-audience-service-designers","title":"Intended Audience: Service Designers","text":"<p>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.</p> <p>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.</p>"},{"location":"service_design/intro/#probe-further","title":"Probe further","text":"<ul> <li>Design and expose services based on containerized resources via the Kubernetes Operator pattern</li> <li>Design and expose services based on NFV artifacts</li> </ul>"},{"location":"service_design/examples/ExposingCRDs_aaS_Example_Calculator/ExposingCRDs_aaS_Example_Calculator/","title":"Exposing Kubernetes Operators as a Service : Offering \"Calculator as a Service\" through OpenSlice","text":""},{"location":"service_design/examples/ExposingCRDs_aaS_Example_Calculator/ExposingCRDs_aaS_Example_Calculator/#intended-audience-service-designers","title":"Intended Audience: Service Designers","text":"<p>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.\" </p> <p>This example will demonstrate the flexibility and capabilities of Kubernetes operators in managing custom resources and automating operational tasks.</p>"},{"location":"service_design/examples/ExposingCRDs_aaS_Example_Calculator/ExposingCRDs_aaS_Example_Calculator/#offering-calculator-as-a-service-through-openslice","title":"Offering \"Calculator as a Service\" through OpenSlice","text":"<ul> <li>We have a service that can accept two integers and an action (SUM, SUB, etc) and returns a result</li> <li>We would like to offer it as a Service through OpenSlice</li> <li>So when a user orders it with some initial parameters, OpenSlice will create it and return the result</li> <li>Also while the service is active, we can do further calculations, until we destroy it.</li> </ul> <p>Assume the following simple CRD of a calculator model accepting two params (spec section) and an action and returning a result (status section)</p> <p>The controller (the calculator code) is implemented in any language and is installed in a Kubernetes cluster</p> <pre><code>\napiVersion: apiextensions.k8s.io/v1\nkind: CustomResourceDefinition\nmetadata:\n name: mycalculators.examples.osl.etsi.org\nspec:\n group: examples.osl.etsi.org\n names:\n kind: MyCalculator\n plural: mycalculators\n singular: mycalculator\n scope: Namespaced\n versions:\n - name: v1alpha1\n schema:\n openAPIV3Schema:\n properties:\n spec:\n properties:\n parama:\n type: integer\n paramb:\n type: integer\n action:\n type: string\n type: object\n status:\n properties:\n result:\n type: integer\n status:\n type: string\n type: object\n type: object\n served: true\n storage: true\n subresources:\n status: {}\n</code></pre> <p>Request to the cluster (through e.g. kubectl apply)</p> <pre><code>apiVersion: examples.osl.etsi.org/v1alpha1\nkind: MyCalculator\nmetadata:\n name: mycalculator.examples.osl.etsi.org\nspec:\n parama: 170\n paramb: 180\n action: 'SUM'\n\n</code></pre> <p>Response</p> <pre><code>apiVersion: examples.osl.etsi.org/v1alpha1\nkind: MyCalculator\nmetadata:\n\u00a0 creationTimestamp: '2023-12-05T12:26:07Z\u2019\n\n<snip>\n\nstatus:\n\u00a0 result: 350\n\u00a0 status: CALCULATED\nspec:\n\u00a0 action: SUM\n\u00a0 parama: 170\n\u00a0 paramb: 180\n\n</code></pre> <p>To perform this through OpenSlice as a Service Specification ready to be ordered we need to do the following:</p>"},{"location":"service_design/examples/ExposingCRDs_aaS_Example_Calculator/ExposingCRDs_aaS_Example_Calculator/#crd-is-saved-automatically-as-resource-specification","title":"CRD is saved automatically as Resource Specification","text":"<p>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.</p> <ul> <li>See also the fully qualified name of the resource specification. <ul> <li>MyCalculator@examples.osl.etsi.org/v1alpha1@docker-desktop@https://kubernetes.docker.internal:6443/</li> <li>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:<ul> <li>MyCalculator@examples.osl.etsi.org/v1alpha1@default_cluster@https://10.10.10.8:6443/</li> <li>MyCalculator@examples.osl.etsi.org/v1alpha1@edge1_cluster@https://172.16.10.10:6443/</li> </ul> </li> <li>Having this OpenSlice can manage resources in multiple clusters</li> </ul> </li> </ul> <p></p> <p>See also the detailed characteristics. See how OpenSlice makes all characteristics automatically flat and expanded with key-value style</p> <p></p>"},{"location":"service_design/examples/ExposingCRDs_aaS_Example_Calculator/ExposingCRDs_aaS_Example_Calculator/#expose-to-users","title":"Expose to Users","text":""},{"location":"service_design/examples/ExposingCRDs_aaS_Example_Calculator/ExposingCRDs_aaS_Example_Calculator/#start-by-creating-a-resourcefacingservicespecification","title":"Start by Creating a ResourceFacingServiceSpecification","text":"<p>From the UI menu create a new Service Specification</p> <p></p> <p></p>"},{"location":"service_design/examples/ExposingCRDs_aaS_Example_Calculator/ExposingCRDs_aaS_Example_Calculator/#creation-of-crd-related-characteristics","title":"Creation of CRD-related characteristics","text":"<ul> <li>We need now to adjust some characteristics of this CRD as Resource Specification.</li> <li>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</li> <li> <p>We need to make OpenSlice aware of when the service will be active. </p> <ul> <li>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) </li> <li>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\"</li> <li>We need also to define the yaml file that OpenSLice will use to create the new resource in the kubernetes cluster</li> <li>We insert the YAML in the characteristic _CR_SPEC</li> </ul> <p>the _CR_SPEC is: </p> </li> </ul> <pre><code>apiVersion: examples.osl.etsi.org/v1alpha1\nkind: MyCalculator\nmetadata:\n name: mycalculator.examples.osl.etsi.org\nspec:\n parama: 170\n paramb: 180\n action: 'SUM'\n\n</code></pre> <p></p> <p>However the values are fixed. How do we allow a user to pass parameters through OpenSlice</p>"},{"location":"service_design/examples/ExposingCRDs_aaS_Example_Calculator/ExposingCRDs_aaS_Example_Calculator/#expose-in-catalog","title":"Expose in Catalog","text":"<p>Create a new CustomerFacingServiceSpecification</p> <pre><code>- Go to the menu Service Specification>New Service Specification\n- Create a service My Calulator and mark it as a Bundle\n- Go to Service Specification Relationships and add MyCalculatorRFS\n- The service will be automatically transformed to a \"CustomerFacingServiceSpecification\"\n- Add the following characteristics as the image shows:\n</code></pre> <p></p>"},{"location":"service_design/examples/ExposingCRDs_aaS_Example_Calculator/ExposingCRDs_aaS_Example_Calculator/#allow-users-to-pass-new-values-through-openslice","title":"Allow users to pass new values through OpenSlice","text":"<p>We need to Create LCM rules in CustomerFacingServiceSpecification:</p> <pre><code>- The goal of the rules is to allow the user to pass parameters to the actual resource towards the cluster.\n- we will create one rule that will pass the parameters just before creating the service (PRE_PROVISION phase)\n- we will create one rule that will pass the parameters while the service is active (SUPERVISION phase)\n- The rules will be the same\n</code></pre> <p></p> <p>If we see one rule it will look like the following:</p> <p></p> <ul> <li>We need to change the _CR_SPEC characteristic of the referenced ResourceFacingServiceSpecification</li> <li>First bring a block from Service>Relationships>Service Refs and drop the \"Service MyCalculatorRFS\" block</li> <li>Then add a list block from Lists</li> <li>Then add the block that modifies a referenced characteristic from Service>Relationships>Service Refs the block \"Set value to characteristic of a Referenced Service\"</li> <li>Add a block for text _CR_SPEC </li> <li>We use a block that changes a String according to variables Text>\"A formatted text replacing variables from List\"</li> <li>See that we have as Input string the YAML string lines<ul> <li>see that parama, paramb has a %d (they accept integers), action is %s (accepts a string)</li> <li>See that the variables tha will replace the %d, %d and %s are an list<ul> <li>the first %d will be replaced with the value from characteristic spec.parama</li> <li>the second %d will be replaced with the value from characteristic spec.paramb</li> <li>the %s will be replaced with the value from characteristic spec.action</li> </ul> </li> </ul> </li> </ul> <p>If we see the SUPERVISION rule it will look like the following:</p> <ul> <li>It contains also the Result field, which takes the value from the referenced service</li> <li>Add a block for the Result field from Service>Number blocks</li> <li>Add a str to int block from Number blocks</li> <li>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\"</li> <li>Add as name the \"status.result\" </li> </ul> <p></p> <p></p> <p>Expose it then to a catalogue for orders through the Service Categories and Service Catalogs</p> <p></p>"},{"location":"service_design/examples/ExposingCRDs_aaS_Example_Calculator/ExposingCRDs_aaS_Example_Calculator/#order-the-service","title":"Order the Service","text":"<p>When a user orders the service, it will look like this:</p> <p></p> <ul> <li>After the Service Order we have 2 services in service inventory on CFS and on RFS. Both have references to values</li> <li>OpenSlice (via CRIDGE service) updates the Resource in Resource Inventory and OSOM updates the Services in Service Inventory</li> <li>The Actual resources are running in the Kubernetes cluster managed by OpenSlice</li> <li>The result is in the characteristic status.result of the running service</li> </ul> <p></p> <p></p>"},{"location":"service_design/examples/ExposingCRDs_aaS_Example_Calculator/ExposingCRDs_aaS_Example_Calculator/#modify-the-running-service","title":"Modify the running service","text":"<p>The user can modify the service</p> <p></p> <ul> <li>After a while the update is applied to the cluster, the controller will pick up the resource update and patch the resource</li> <li>OpenSlice (via CRIDGE service) updates the Resource in Resource Inventory and OSOM updates the Services in Service Inventory</li> <li>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)</li> </ul> <p></p>"},{"location":"service_design/kubernetes/ExposingKubernetesResources/","title":"Expose and manage Kubernetes Custom Resource Definitions (Operators) in a Kubernetes Cluster","text":"<p>OpenSlice is capable of exposing Kubernetes Resources and Definitions as Service Specifications</p>"},{"location":"service_design/kubernetes/ExposingKubernetesResources/#intended-audience-service-designers","title":"Intended Audience: Service Designers","text":"<p>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.</p> <p>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.</p> <ol> <li> <p>OpenSlice is capable to:</p> <ul> <li>Create and manage Custom Resources (CRs) using installed CRDs on a target Kubernetes cluster.</li> <li>Facilitate complex orchestration scenarios by wrapping Kubernetes APIs as TMF APIs and models.</li> <li>Handles connectivity to a Kubernetes cluster and manages the lifecycle of CRDs</li> <li>Wraps the Kubernetes API, Receives and provides resources towards other OpenSlice services via the service bus</li> </ul> </li> <li> <p>Enabling Loose Coupling and Orchestration</p> <ul> <li>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.</li> <li>Familiar Deployment: Developers can create and deploy applications using familiar tools such as Helm charts, simplifying the process and reducing the learning curve.</li> </ul> </li> <li> <p>Ecosystem Reusability</p> <ul> <li>OpenSlice capitalizes on the extensive Kubernetes ecosystem, particularly focusing on operators (CRDs).</li> <li>Key repositories and hubs such as artifacthub.io and Operatorhub.io can be utilized for finding and deploying operators.</li> </ul> </li> <li> <p>Service Catalog Exposure and Deployment</p> <ul> <li>OpenSlice can expose CRs in service catalogs, facilitating their deployment in complex scenarios.</li> <li>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.</li> </ul> </li> </ol>"},{"location":"service_design/kubernetes/ExposingKubernetesResources/#approach","title":"Approach","text":"<p>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.</p> <p>The following image illustrates the approach.</p> <p></p> <ol> <li>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</li> <li>Service Orders can be created for this service specification. </li> <li>OSOM creates a Resource in OSL Resource inventory and requests new Custom Resource (CR) in the target cluster<ul> <li>The resource is created in a specific namespace (for example the UUID of the Service Order)</li> <li>A CR in a cluster will be mapped in TMF model as a Resource in the resource Inventory</li> <li>Other related resources created by the CRD Controller within the namespace are automatically created in OSL Resource Inventory under the same Service Order</li> </ul> </li> </ol>"},{"location":"service_design/kubernetes/ExposingKubernetesResources/#awareness-for-crds-and-crs-in-cluster","title":"Awareness for CRDs and CRs in cluster","text":"<p>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.</p> <p>When installing OpenSlice you can configure at least one management cluster. OpenSlice connects via a provided kubeconf</p> <ul> <li>On Start up OSL tries to register this cluster and context to OSL catalogs.</li> <li>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</li> <li>Resources created by OpenSlice have labels, e.g. (org.etsi.osl.*)</li> </ul>"},{"location":"service_design/kubernetes/ExposingKubernetesResources/#expose-crds-as-service-specifications-in-openslice-catalogs","title":"Expose CRDs as Service Specifications in OpenSlice catalogs","text":"<p>A CRD by default is exposed as a Resource Specification</p> <p>To ensure unique names across the clusters that OpenSlice can manage, the name of a CRD is constructed as follows:</p> <p><code>Kind @ ApiGroup/version @ ContextCluster @ masterURL</code></p> <p>For example you might see resource Specifications like:</p> <pre><code>- ```Application@argoproj.io/v1alpha1@kubernetes@https://10.10.10.144:6443/```\n- ```IPAddressPool@metallb.io/v1beta1@kubernetes@https://10.10.10.144:6443/```\n- ```Provider@pkg.crossplane.io/v1@kubernetes@https://10.10.10.144:6443/```\n</code></pre> <p>All attributes of the CRD are translated into characteristics</p> <p>The following specific characteristics are added:</p> <pre><code> - _CR_SPEC: Used for providing the json Custom Resource description to apply\n - _CR_CHECK_FIELD: Used for providing the field that need to be checked for the resource status\n - _CR_CHECKVAL_STANDBY: Used for providing the equivalent value from resource to signal the standby status\n - _CR_CHECKVAL_ALARM: Used for providing the equivalent value from resource to signal the alarm status\n - _CR_CHECKVAL_AVAILABLE: Used for providing the equivalent value from resource to signal the available status\n - _CR_CHECKVAL_RESERVED: Used for providing the equivalent value from resource to signal the reserved status\n - _CR_CHECKVAL_UNKNOWN: Used for providing the equivalent value from resource to signal the unknown status\n - _CR_CHECKVAL_SUSPENDED: Used for providing the equivalent value from resource to signal the suspended status\n</code></pre> <ol> <li> <p>Create a new Service Specification and use this Resource Specification in Resource Specification Relationships</p> <ul> <li>Then the Service Specification is saved as ResourceFacingServiceSpecification</li> </ul> <p>1.1. You can give at this stage values to the characteristics:</p> <pre><code>- _CR_SPEC, \n- _CR_CHECK_FIELD\n- _CR_CHECKVAL_STANDBY\n- _CR_CHECKVAL_ALARM\n- _CR_CHECKVAL_AVAILABLE\n- _CR_CHECKVAL_RESERVED\n- _CR_CHECKVAL_UNKNOWN\n- _CR_CHECKVAL_SUSPENDED\n</code></pre> <p>1.2. You can now create LCM rules if you wish</p> </li> <li> <p>Create a new Service Specification and use the Resource Facing Service Specification in Service Specification Relationships</p> <ul> <li>Then the Service Specification is saved as CustomerFacingServiceSpecification</li> </ul> <p>2.1. You can give at this stage values to the characteristics: </p> <pre><code>- _CR_SPEC, \n- _CR_CHECK_FIELD\n- _CR_CHECKVAL_STANDBY\n- _CR_CHECKVAL_ALARM\n- _CR_CHECKVAL_AVAILABLE\n- _CR_CHECKVAL_RESERVED\n- _CR_CHECKVAL_UNKNOWN\n- _CR_CHECKVAL_SUSPENDED\n</code></pre> <p>2.2. You We can create LCM rules for this new Service Specification</p> <p>2.3. You Expose configurable values for users to configure during service order</p> </li> </ol> <p></p>"},{"location":"service_design/kubernetes/ExposingKubernetesResources/#service-orchestration-and-crdscrs","title":"Service Orchestration and CRDs/CRs","text":"<p>OSOM - OpenSlice Service Orchestrator, checks the presence of attribute _CR_SPEC at the RFS to make a request for a CR deployment</p> <ul> <li>_CR_SPEC is a JSON or YAML string that is used for the request<ul> <li>It is similar to what one will do with e.g. a kubectl apply</li> <li>There are tools to translate a yaml file to a json</li> </ul> </li> </ul> <p>LCM rules can be used to change attributes of this yaml/json file, before sending this for orchestration</p>"},{"location":"service_design/kubernetes/ExposingKubernetesResources/#mapping-the-cr-lifecycle-that-is-defined-in-the-crd-with-the-openslice-tmf-based-resource-lifecycle","title":"Mapping the CR lifecycle that is defined in the CRD with the OpenSLice (TMF-based) resource Lifecycle","text":"<p>OpenSlice adds automatically as we see the following characteristics: </p> <pre><code> - _CR_CHECK_FIELD\n - _CR_CHECKVAL_STANDBY\n - _CR_CHECKVAL_ALARM\n - _CR_CHECKVAL_AVAILABLE\n - _CR_CHECKVAL_RESERVED\n - _CR_CHECKVAL_UNKNOWN\n - _CR_CHECKVAL_SUSPENDED\n</code></pre> <p>These characteristics instrument OpenSlice services to manage and reflect the lifecycle of a kubernetes resource to OpenSlice's (TMF based) lifecycle</p> <ul> <li>_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) </li> <li>_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) </li> <li>_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) </li> <li>_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) </li> <li>_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) </li> <li>_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) </li> <li>_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) </li> </ul>"},{"location":"service_design/kubernetes/ExposingKubernetesResources/#probe-further","title":"Probe further","text":"<ul> <li>See examples of exposing operators via OpenSlice:<ul> <li>Exposing Kubernetes Operators as a Service : Offering \"Calculator as a Service\" through OpenSlice</li> </ul> </li> <li>Learn more about CRIDGE, the service in OSL that manages CRDs/CRs</li> </ul>"},{"location":"service_design/kubernetes/helm/HELM_Installation_aaS_Jenkins_Example/","title":"Example: Offer Jenkins as a Service via Openslice","text":"<p>Before reading this example please make sure that you went through the Design Helm as a Service </p> <p>We will use the <code>Kind: Application</code> of ArgoCD and create a ResourceFacingServiceSpecification for Jenkins</p> <pre><code>1. Go to Service Specifications\n2. Create New Specification\n3. Give a Name, eg. jenkinsrfs\n4. Go to Resource Specification Relationships\n5. Assign ```Application@argoproj.io/v1alpha1@kubernetes@https://10.10.10.144:6443/```\n</code></pre> <p></p> <p>Focus now on the characteristics configuration.</p> <p>First we need to map the lifecycle of ArgoCD Application to TMF Resource State</p> <p></p> <p>In ArgoCD the field health.status has the value that we need to check (Healty, Progressing, etc)</p> <p>The _CR_SPEC can be designed first in a YAML or json editor. Let's see a YAML definition:</p> <p>```</p> <p>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: 4.6.1 chart: jenkins helm: values: | controller: service: type: ClusterIP syncPolicy: automated: prune: true selfHeal: true allowEmpty: false syncOptions: - Validate=false - CreateNamespace=true - PrunePropagationPolicy=foreground - PruneLast=true - RespectIgnoreDifferences=true ```</p> <p>NOTICE</p> <p>On each installation OSOM will change the name of the resource in order to be unique (will have a UUID)</p> <p><code>name: openslice-jenkins</code> </p> <p>destination namespace that ArgoCD will use is the name <code>opencrdtest</code></p> <p><code>destination: namespace: opencrdtest</code></p> <p>This implies that ArgoCD installs the Jenkins always in the same namespace</p> <p>To avoid this we will create a simple pre-provision rule to change the namespace properly</p> <p>See the following image: </p> <p></p> <ol> <li>Drag-Drop the _CR_SPEC characteristic of jenkinsrfs from the Service>Text blocks</li> <li>Drag-Drop Text>Formatted text block</li> <li>Drag-Drop Text>Multi-line text input block</li> <li>Copy paste the YAML text</li> <li>Change the spec: destination:namespace to the value %s</li> <li>Drag-Drop Lists>Create list with block delete 2 items (click the gear icon). Connect it to formatted text block</li> <li>Drag-Drop Context>Current Service Order block and select the id. Connect it to the List</li> <li>Save the PRE_PROVISION Rule</li> </ol>"},{"location":"service_design/kubernetes/helm/HELM_Installation_aaS_Jenkins_Example/#expose-the-service-to-your-users","title":"Expose the service to your users","text":"<p>Expose then as CustomerFacingServiceSpecification by using the previous RFSS as Service Specification Relationship 1. Create a Jenkins service and mark as Bundle and save it 2. Go to Service Specification Relationships and assign Jenkinsrfs 3. Add also a Logo if you wish</p> <p></p> <p></p> <p>Expose it now to a Category and a Catalog to be available for ordering.</p> <p></p>"},{"location":"service_design/kubernetes/helm/HELM_Installation_aaS_Jenkins_Example/#order-the-service","title":"Order the service","text":"<p>Order the service from the catalog. </p> <p>Soon the order will be completed and the Services will be active</p> <p></p>"},{"location":"service_design/kubernetes/helm/HELM_Installation_aaS_Jenkins_Example/#how-to-access-the-jenkins-installation","title":"How to access the Jenkins installation:","text":"<p>From the Supporting services of the Service Order, select the ResourceFacingService (jenkinsrfs)</p> <p>The ResourceFacingService has also supporting resources in resource inventory.</p> <p></p> <p>One is the resource reference to the application (e.g. cr_tmpname...), the other is a secret (e.g. cr87893...). </p> <p>Click to go to the secret resource (This is in the Resource inventory of OpenSlice)</p> <p></p> <p>Use them to login in your Jenkins.</p> <p>Exposing Jenkins to you external is a matter of cluster configuration and request (nodeport, load balancing, etc)! This is not a topic for this example</p>"},{"location":"service_design/kubernetes/helm/design_helmaas/","title":"Expose HELM charts as Service Specifications","text":"<p>Manage Helm charts installations via OpenSlice Service Specifications and Service Orders.</p>"},{"location":"service_design/kubernetes/helm/design_helmaas/#intended-audience-service-designers","title":"Intended Audience: Service Designers","text":"<p>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. </p> <p>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</p> <p>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:</p> <pre><code> - Reduces the complexity of deploying Microservices\n - Enhances deployment speed\n - Developers already know the technology\n</code></pre> <p>There are many Helm charts and Helm repositories there that are ready to be used</p> <p>Enable loose coupling and more orchestration scenarios</p> <p>Developers create and deploy applications in things they already know (e.g. Helm charts)</p> <p>Use the TMF models as wrapper entities around Helm charts</p> <p>Use OpenSlice to expose them in service catalogs and deploy them in complex scenarios (service bundles) involving also other systems:</p> <pre><code>- Include e.g. RAN controllers, \n- Pass values through life cycle rules from one service to another, \n- Manage multiple Helms in multiple clusters\n</code></pre>"},{"location":"service_design/kubernetes/helm/design_helmaas/#the-installation-of-helm-charts-is-based-on-openslice-crd-support","title":"The installation of HELM charts is based on OpenSlice CRD support","text":"<p>Please read more here</p> <p>For installing HELM charts we will use ArgoCD a well known Kubernetes-native continuous deployment (CD) tool </p> <p>ArgoCD is a Kubernetes-native continuous deployment (CD) tool</p> <p>While just deploying Heml charts is just a scenario for ArgoCD , in future one can exploit it for many things</p> <p>Despite some other tools like FluxCD, it provides also a UI which is useful for management and troubleshooting</p> <p>We will mainly use the CRD of <code>Kind: Application</code> that ArgoCD can manage</p> <p>Before proceeding, install ArgoCD in your management cluster, by following ArgoCD instructions</p> <p>As soon as you install ArgoCD, OpenSlice is automatically aware for specific new Kinds. The one we will use is is the <code>Kind: Application</code> that ArgoCD can manage under the apiGroup argoproj.io</p> <p>Browse to Resource Specifications. You will see an entry like the following:</p> <p><code>Application@argoproj.io/v1alpha1@kubernetes@https://10.10.10.144:6443/</code></p> <p>see image: </p> <p></p>"},{"location":"service_design/kubernetes/helm/design_helmaas/#whats-next","title":"What's next","text":"<p>See the Example: Offer Jenkins as a Service via Openslice </p>"},{"location":"service_design/lcmrules/intro/","title":"LCM Rules introduction","text":"<p>Lifecycle Management Rules: Defining complex conditions and actions during the lifecycle of a service and any necessary modifications throughout the service lifecycle.</p>"},{"location":"service_design/lcmrules/intro/#intended-audience-service-designers","title":"Intended Audience: Service Designers","text":"<p>In Naas LCM Introduction it was presented briefly the LCM Rules concept.</p> <p>This section goes deeply on how Service Designers can use them.</p> <p>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:</p> <ul> <li>PRE_PROVISION</li> <li>CREATION</li> <li>AFTER_ACTIVATION </li> <li>SUPERVISION </li> <li>AFTER_DEACTIVATION </li> </ul> <p>The following figure displays the different phases that the rules are performed, during the lifecycle of a Network Slice Instance.</p> <p></p> <ul> <li>PRE_PROVISION rules: Run only once just before creating a service with a given priority. </li> <li>CREATION rules: Run while the referenced service dependencies of a service are created</li> <li>AFTER_ACTIVATION rules: Run only once just after a service get the ACTIVE state</li> <li>SUPERVISION rules: Run when a characteristic of a service is changed and the service is in the ACTIVE state </li> <li>AFTER_DEACTIVATION rules: Run only once just after a service get the INACTIVE/TERMINATED state </li> </ul> <p>In general the rules allow to perform many actions during service LCM. Thes are some examples:</p> <ul> <li>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</li> <li>Translate GST/NEST parameter values to other values passed later to NFVO for instantiation or control</li> <li>Define complex OSM Configs based on other dependencies and passing variables</li> <li>Define any dependencies when creating the referenced services</li> <li>Dynamically include new service dependencies</li> <li>Create new service orders so include dynamically other services</li> <li>Call external (RESTful) services (via http(s), define payload, examine response)</li> </ul>"},{"location":"service_design/lcmrules/intro/#examine-if-the-rules-are-executed-successfully","title":"Examine if the rules are executed successfully","text":"<p>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.</p>"},{"location":"service_design/lcmrules/intro/#lcm-rules-and-osom-service-orchestration","title":"LCM Rules and OSOM Service Orchestration","text":"<p>OSOM is the responsible service for executing the rules on a specific phase. The following image explains the design in the BPMN phases:</p> <p></p>"},{"location":"service_design/lcmrules/intro/#define-rules","title":"Define rules","text":"<p>Rules are defined when designing a Service Spec. Here is an example of a list of rules:</p> <p></p> <p>Execution order of rules on a specific phase is random</p> <ul> <li>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.</li> </ul>"},{"location":"service_design/lcmrules/intro/#definition-language","title":"Definition language","text":"<ul> <li>The visual language that Openslice used is based on Google's Blockly (see https://developers.google.com/blockly)</li> <li>The blockly graph is automatically translated to Java internally and then dynamically executed during orchestration phases.</li> </ul> <p>The following figure is an example of such a rule design. The rule for example will run in PRE_PROVISION phase:</p> <p></p> <ul> <li>The goal of the above rule is to properly define a variable AreaCodes given the chosen AreaOfService from a Service Order.</li> <li>On the right side the user can define some rule properties or observe the underlying generated java code.</li> </ul>"},{"location":"service_design/lcmrules/intro/#the-blocks-library","title":"The blocks library","text":"<p>The following images describe some blocks found in the library.</p> <p>Blockly has syntax rules. It helps with colours to define them. </p> <p>So for example a parameter that is a Number cannot be \"glued\" with a String. Will need some conversion first</p> <p> </p>"},{"location":"service_design/lcmrules/intro/#examples-of-rules","title":"Examples of Rules","text":"<p>The following images provide some examples of rules.</p>"},{"location":"service_design/lcmrules/intro/#define-variables-according-to-cases","title":"define variables according to cases","text":"<p>In the following example we :</p> <ul> <li>define a String variable. </li> <li>Then according to the Area of Service selected from the Service Order of the Service Specification we need to define it properly.</li> <li>We output the value to the OSOM Log</li> <li>Define dynamically the value of another parameter (This is fictional) and then do some other condition check</li> </ul> <p>The strAreaCodes could be passed then e.g. to NFVO for instantiation of services to these cells.</p> <p></p>"},{"location":"service_design/lcmrules/intro/#define-complex-osm-configs-for-day-0","title":"Define complex OSM configs for DAY 0","text":"<p>The following displays some complex examples for defining the parameters to pass to the NFV. In this case is OSM.</p> <ul> <li> <p>NOTE: The OSM_CONFIG characteristic of a service is the one that it is used in orchestration to instantiate NS from OSM</p> </li> <li> <p>check the variable strTargetsParam. It is passed to the variable strOsmConfig3 which is executed if the Number of Cameras is more than 100. </p> </li> <li>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.</li> <li>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!)</li> <li>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</li> </ul> <p></p>"},{"location":"service_design/lcmrules/intro/#define-and-instantiate-different-services-according-to-service-order-request","title":"Define and instantiate different services according to Service Order request","text":"<p>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.</p> <p>There are different ways to accomplish this:</p> <ul> <li>create dynamically New Service Orders of RFSs with equivalent quality of Services</li> <li>change for example the VIMs that you deploy the NS</li> <li>change the NSD (that is use different VNFs)</li> </ul> <p>The following image displays for example the latter case.</p> <p></p>"},{"location":"service_design/lcmrules/intro/#call-an-external-restful-service","title":"Call an external RESTful service","text":"<p>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)</p> <p></p> <p></p>"},{"location":"service_design/lcmrules/intro/#create-new-service-orders","title":"Create New Service Orders","text":"<p>The following example calls to Order a New Service Specification with specific Parameter Values</p> <p></p>"},{"location":"service_design/lcmrules/intro/#probe-further","title":"Probe further","text":"<ul> <li>Check our examples for more usages</li> <li>See next the complete specification</li> </ul>"},{"location":"service_ordering/ordering_services/","title":"Service Ordering","text":""},{"location":"service_ordering/ordering_services/#intended-audience-users","title":"Intended Audience: Users","text":""}]}
\ No newline at end of file
+{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Introduction","text":"<p>version: 2024Q2 - SNAPSHOT</p> <p>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.</p>"},{"location":"#usage","title":"Usage","text":"<p>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. </p> <p></p> <p>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. </p>"},{"location":"#an-end-to-end-e2e-service-orchestration-framework","title":"An end-to-end (E2E) service orchestration framework","text":"<p>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:</p> <ul> <li>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.</li> <li>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.</li> <li>Service Design and Creation tharough service templates based on predefined models for creating services.</li> <li>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.</li> <li>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</li> <li>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.</li> <li>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.</li> <li>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.</li> </ul>"},{"location":"#an-e2e-service-orchestration-workflow","title":"An E2E service orchestration workflow","text":"<p>In general an E2E service orchestration workflow includes the following phases:</p> <ul> <li>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.</li> <li>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.</li> <li>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</li> <li>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.</li> <li>Lifecycle Management: The orchestration framework handles updates, scaling, and any necessary modifications throughout the service lifecycle.</li> <li>At the end of the service period, resources are decommissioned and reclaimed.</li> </ul>"},{"location":"#openslice-for-service-providers","title":"OpenSlice for Service Providers","text":"<p>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.</p> <p>There are various portals offering UI friendly access to users acting as Service Providers:</p> <ul> <li>The Services portal allows Service Providers to design and expose services.</li> <li>The Resource portal allows users to access resource specifications and running resources in resource inventory.</li> <li>The NFV portal allows users to manage NFV artifacts and onboard them to a target MANO/NFV Orchestrator.</li> <li>The Testing portal allows Service Providers to manage test artifacts</li> <li>The Products portal allows Service Providers to expose services as products</li> </ul>"},{"location":"#openslice-for-service-consumers","title":"OpenSlice for Service Consumers","text":"<p>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:</p> <ul> <li>The Services portal allows Service Consumers to select and order predefined services.</li> <li>The Resource portal allows users to access running resources in resource inventory.</li> <li>The NFV portal allows users to self-manage NFV artifacts and onboard them to a target MANO/NFV Orchestrator.</li> <li>The Testing portal allows Service Consumers to manage test artifacts</li> <li>The Products portal allows Service Consumers to expose services as products</li> </ul> <p>3rd party applications can use OpenSlice through TMForum Open APIs.</p>"},{"location":"#live-demo","title":"Live Demo","text":"<p>Check a live demo of OpenSlice in the following pages:</p> <p>(username=admin, password=openslice or username=admin, password=changeme)</p> <ul> <li>OpenSlice demo: http://portal.openslice.io/</li> <li>OpenSlice Service Catalogs and ordering: http://portal.openslice.io/services/</li> <li>OpenSlice NFV Services onboarding: http://portal.openslice.io/nfvportal </li> </ul>"},{"location":"#probe-further","title":"Probe further","text":"<ul> <li>Installing OpenSlice. See the Deployment of OpenSlice</li> <li>Learn more on [how OpenSlice supports Network as a Service(NaaS)](./naas/introduction</li> <li>Who is implementing OpenSlice? See OSL ETSI SDG</li> <li>How OpenSlice works? See the Architecture of OpenSlice</li> </ul>"},{"location":"OpenSlice_deployment_examples/","title":"OpenSlice deployment examples","text":"<p>Here are some examples from past and current efforts that use OpenSlice in various cases.</p>"},{"location":"OpenSlice_deployment_examples/#5ginfire-eu-project2018","title":"5GinFIRE EU project(2018)","text":"<ul> <li>MultiVIM approach</li> <li>9 Testbeds</li> <li>Automotive, Smart City, eHeath, \u000bPPDR, Media, SDR, Cloud</li> <li>22 Experiment proposals from Verticals</li> <li>100+ Users</li> <li>VxF catalog: </li> <li>150+ ONBOARDED VxFs</li> <li>OSM TWO, FOUR, FIVE</li> <li>50+ are public to be reused</li> <li>NSD catalog: </li> <li>90+ ONBOARDED NSDs</li> <li>30+ are public to be reused</li> <li>500+ Deployment requests \u000b(orchestrations) performed</li> </ul> <p>[</p>"},{"location":"OpenSlice_deployment_examples/#5g-vinni-eu-project-2020","title":"5G-VINNI EU project (2020)","text":"<ul> <li>Multi-vendor challenge \u2013 Commercial and opensource</li> <li>5G services on multiple sites</li> <li>Introduction of TMFORUM models and APIs </li> </ul> <p>[</p>"},{"location":"OpenSlice_deployment_examples/#5gasp-eu-project-2021-2024","title":"5GASP EU project (2021-2024)","text":"<ul> <li>Support a multi-site CI/CD testing automated DevOps cycle for network Applications</li> <li>Multiple NFVOs</li> <li>Introducing Service Test models</li> <li>Introducing the Product models for a network application marketplace</li> </ul> <p>[</p>"},{"location":"OpenSlice_deployment_examples/#fidal-eu-project-2023-","title":"FIDAL EU project (2023-)","text":"<ul> <li>Support multi-site automated testing</li> <li>Multiple testbeds/ different APIs</li> </ul> <p>[</p>"},{"location":"OpenSlice_deployment_examples/#across-eu-project-2023-","title":"ACROSS EU project (2023-)","text":"<ul> <li>Used as a cross-domain orchestrator</li> <li>Support the multi-domain orchestrator</li> <li>Support Zero-touch provisioning concepts</li> </ul> <p>[</p>"},{"location":"OpenSlice_deployment_examples/#incode-eu-project-2023-","title":"INCODE EU project (2023-)","text":"<ul> <li>Support the provisioning of end-to-end domain services</li> </ul> <p>[</p>"},{"location":"OpenSlice_deployment_examples/#imagineb5g-eu-project-2023-","title":"IMAGINEB5G EU project (2023-)","text":"<ul> <li>Support the provisioning of end-to-end domain services</li> </ul>"},{"location":"OpenSlice_deployment_examples/#etsi-zsm-poc-2","title":"ETSI ZSM PoC #2","text":"<ul> <li>Automated Network Slice Scaling in Multi-Site Environments</li> </ul> <p>[</p>"},{"location":"alarms_actions/","title":"Alarms","text":"<p>In Openslice parts of TMF642 Alarm Management API are currently implemented. Alarms can be managed through the TMF API endpoint as well as the UI.</p>"},{"location":"alarms_actions/#alarms-and-actions","title":"Alarms and Actions","text":"<p>Note: Actions is an experimental feature. We expect to have a more mature solution in future. The component in the architecture is the Openslcie Assurance Services</p> <p>Alarms can be automatically resolved by specific actions. Today only the following actions are offered.</p> <ul> <li>execDay2</li> <li>scaleServiceEqually</li> </ul>"},{"location":"alarms_actions/#execday2","title":"execDay2","text":"<p>Usually used to perform a Day2 configuration (towards OSM). To use it, Create a New Action Specification Name=execDay2 as following</p> <p></p> <p>Now make a Service Order for your service. In this example \u03c2\u03b5 used a cirros NSD</p> <p>Create a New Action Rule for the running services as the following example:</p> <p></p> <p>The scope is the running cirros service. </p> <p>Params should be paramname=value;paramname2=value2;paramname3=value3 (must exist in the VNF otherwise OSM will raise an error).</p> <p>In this case should be filename=test.txt</p> <p>Primitive=touch</p> <p>ServiceId = select the service which will accept the Day2. In this case is the same</p> <p>To test it:</p> <p>Go to the Service Inventory and select the active Service.</p> <p>Note the UUID of the service (e.g. c4e7990a-e174-4cd2-9133-b10e56721e08 copy from address bar), DeploymentRequestID and NSDID from characteristics</p> <p>You can either use the UUID of the service or the DeploymentRequestID and POST to the Alarms endpoint ( /tmf-api/alarmManagement/v4/alarm)</p> <p>If the DeploymentRequestID is used then POST:</p> <pre><code>\n{\n \"alarmRaisedTime\": \"2021-06-29T12:30:24.675Z\",\n \"alarmReportingTime\": \"2021-06-29T12:30:54.675Z\",\n \"state\": \"raised\",\n \"alarmType\": \"qualityOfServiceAlarm\",\n \"probableCause\": \"thresholdCrossed\",\n \"ackState\": \"unacknowledged\",\n \"perceivedSeverity\": \"major\",\n \"sourceSystemId\": \"mano-client-service\",\n \"alarmDetails\": \"NSID=3;DeploymentRequestID=1\",\n \"specificProblem\": \"myalram raised\"\n}\n\n</code></pre> <p>If the UUID is used then POST:</p> <pre><code>\n{\n \"alarmRaisedTime\": \"2021-06-29T12:30:24.675Z\",\n \"alarmReportingTime\": \"2021-06-29T12:30:54.675Z\",\n \"state\": \"raised\",\n \"alarmType\": \"qualityOfServiceAlarm\",\n \"probableCause\": \"thresholdCrossed\",\n \"ackState\": \"unacknowledged\",\n \"perceivedSeverity\": \"major\",\n \"sourceSystemId\": \"mano-client-service\",\n \"alarmDetails\": \"analarm\",\n \"specificProblem\": \"myalram raised\",\n \"affectedService\": [\n {\n \"id\": \"c4e7990a-e174-4cd2-9133-b10e56721e08\"\n }\n ]\n\n}\n\n</code></pre> <p>The Alarm to be created must have the affected Service ID equal to the running service from the scope (the cirros_ns)</p> <p>Go to service inventory you will see the notes and also the service characteristics for any EXEC_ACTION updates</p> <p>You can also adjust the alarm conditions. They must match true so the alarm to be acknowledged So if another external service raises an Alarm (with POST) for the running service, a Day2 will be performed on another Service</p>"},{"location":"alarms_actions/#scaleserviceequally","title":"scaleServiceEqually","text":"<p>This action is used from getting a scaling event from OSM. Please see the next demo for details on how it works</p>"},{"location":"alarms_actions/#prototype-demo","title":"Prototype demo","text":"<p>You can watch how we used the prototype on the following ETSI ZMS PoC #2</p> <ul> <li>ETSI ZMS PoC #2: https://www.etsi.org/events/1905-webinar-zsm-poc-2-showcase-automated-network-slice-scaling-in-multi-site-environments/</li> </ul>"},{"location":"config_intro/","title":"Configuring and managing OpenSlice","text":""},{"location":"config_intro/#intended-audience-openslice-administrators","title":"Intended Audience: OpenSlice administrators","text":"<p>This section provides information on how to configure and manage different aspect of OpenSlice while in operation. For example:</p> <ul> <li>Manage user roles and access in Keycloak</li> <li>Configure/Manage NFVOs</li> <li>Advanced configuration scenarios</li> </ul>"},{"location":"deployment/","title":"OpenSlice Deployment","text":"<p>This section is meant to guide the user through the installation of OpenSlice. </p>"},{"location":"deployment/#intended-audience-openslice-administrators","title":"Intended Audience: OpenSlice administrators","text":"<p>Following, you may thorough guides depending on the installation type of your choice:</p> <ul> <li>Installing via Docker Compose guide</li> <li>Installing via Kubernetes guide</li> </ul>"},{"location":"deploymentCompose/","title":"OpenSlice Deployment Guide with Docker Compose","text":""},{"location":"deploymentCompose/#intended-audience-openslice-administrators","title":"Intended Audience: OpenSlice administrators","text":""},{"location":"deploymentCompose/#requirements","title":"Requirements","text":""},{"location":"deploymentCompose/#hardware-requirements","title":"Hardware requirements:","text":"Minimum Hardware Requirements Recomended Hardware Requirements 4 CPU cores 8 CPU cores 8 GB RAM 16 GB RAM 30 GB storage 50 GB storage"},{"location":"deploymentCompose/#software-requirements","title":"Software Requirements:","text":"<ul> <li>Docker: A running environment for Docker Compose services</li> </ul>"},{"location":"deploymentCompose/#preparing-the-environment","title":"Preparing the environment","text":""},{"location":"deploymentCompose/#1-backup-your-previous-database-if-necessary","title":"1. Backup your previous database if necessary:","text":"<pre><code>sudo docker exec amysql /usr/bin/mysqldump -u root --password=letmein ostmfdb > backup_ostmfdb.sql\n</code></pre>"},{"location":"deploymentCompose/#2-install-docker","title":"2. Install docker","text":"<p>Since July 2023 Docker Compose V1 stopped receiving updates. OpenSlice fully reverted to Compose V2, which is integrated in the Docker installation.</p>"},{"location":"deploymentCompose/#3-configure-containers-to-properly-resolve-the-dns-of-your-domain-optional","title":"3. Configure containers to properly resolve the DNS of your domain (optional)","text":"<pre><code>sudo nano /etc/docker/daemon.json\n</code></pre> <p>and add:</p> <pre><code>{ \n \"dns\": [\"8.8.8.8\", \"8.8.4.4\"]\n}\n</code></pre> <p>After editing daemon.json restart docker daemon for the changes to take place</p> <pre><code>sudo systemctl restart docker\n</code></pre>"},{"location":"deploymentCompose/#downloading-the-project","title":"Downloading the project","text":""},{"location":"deploymentCompose/#1-create-a-new-folder-to-download-the-project","title":"1. Create a new folder to download the project","text":"<pre><code>mkdir openslice\n</code></pre> <pre><code>cd openslice\n</code></pre>"},{"location":"deploymentCompose/#2-download-the-deployment-script","title":"2. Download the deployment script","text":"<p>Download the deployment / environment preparation script</p> <pre><code>wget https://labs.etsi.org/rep/osl/code/org.etsi.osl.main/-/raw/develop/compose/deploy.sh\n</code></pre> <p>Make it executable</p> <pre><code>sudo chmod +x deploy.sh\n</code></pre>"},{"location":"deploymentCompose/#3-run-the-deployment-script","title":"3. Run the deployment script","text":"<p>OpenSlice is a multi repo project. This script selects the same branch for all repositories of the project to pull from.</p> <p>After that it builds the respective jar files locally and installs all the npm packages needed for the UI.</p> <p>If you run the script without selecting a branch the the main branch is going to be selected.</p> <p>We recommend:</p> <ul> <li>main branch for the most stable experience and</li> <li>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)</li> </ul> <pre><code>sudo ./deploy.sh develop #[or replace main with other branch name]\n</code></pre> <p>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.</p>"},{"location":"deploymentCompose/#configure-docker-compose-services","title":"Configure Docker Compose services","text":""},{"location":"deploymentCompose/#1-create-configuration-specific-docker-compose-file-from-the-template","title":"1. Create configuration specific Docker Compose file from the template","text":"<pre><code>cd org.etsi.osl.main/compose/\n</code></pre> <pre><code>sudo cp docker-compose.yaml.configure docker-compose.yaml\n</code></pre>"},{"location":"deploymentCompose/#2-configure-mysql-portal-container-optional","title":"2. Configure mysql-portal container (optional)","text":"<ol> <li>In folder <code>org.etsi.osl.main/compose/mysql-init</code> edit the file <code>01-databases.sql</code>.</li> <li>In the <code>org.etsi.osl.main/compose/docker-compose.yaml</code> edit the credentials of the users that services use to connect to the databases, if you wish.<ul> <li>portaluser (default is 12345) and</li> <li>keycloak (default is password)</li> </ul> </li> </ol>"},{"location":"deploymentCompose/#3-configure-keycloak-container-optional","title":"3. Configure keycloak container (optional)","text":"<ol> <li> <p>If you made changes to keycloak's mysql credentials:</p> <p>In folder <code>org.etsi.osl.main/compose/</code> edit the file <code>docker-compose.yaml</code>.</p> </li> </ol> <pre><code>DB_DATABASE: keycloak\nDB_USER: keycloak\nDB_PASSWORD: password\n</code></pre> <ol> <li> <p>If you want to change the keycloak admin password:</p> <p>In folder <code>org.etsi.osl.main/compose/</code> edit the file <code>docker-compose.yaml</code></p> </li> </ol> <pre><code>KEYCLOAK_PASSWORD: Pa55w0rd\n</code></pre>"},{"location":"deploymentCompose/#4-configure-bugzilla-container-optional","title":"4. Configure bugzilla container (optional)","text":"<p>If you want to utilise the Bugzilla connector:</p> <p>In folder <code>org.etsi.osl.main/compose/</code> edit the file <code>docker-compose.yaml</code></p> <pre><code>SPRING_APPLICATION_JSON: '{\n \"spring.activemq.brokerUrl\": \"tcp://anartemis:61616?jms.watchTopicAdvisories=false\",\n \"spring.activemq.user\": \"artemis\",\n \"spring.activemq.password\": \"artemis\",\n \"bugzillaurl\":\"\",\n \"bugzillakey\":\"\",\n \"main_operations_product\":\"\"\n}'\n</code></pre> <p>And add the provided Bugzilla installation information:</p> <pre><code>\"bugzillaurl\":\"bugzillaurl.xx:443/bugzilla/\",\n\"bugzillakey\":\"exampleKeyeqNNwxBlgxZgMEIne0Oeq0Bz\",\n\"main_operations_product\":\"Main Site Operations\" // this is the default product to issue tickets\n</code></pre> <p>Bugzilla should have the following components under the specified product: </p> <ul> <li>NSD Deployment Request: Component used to schedule deployment req </li> <li>Onboarding: Issues related to VNF/NSD Onboarding </li> <li>Operations Support: Default component for operations support </li> <li>Validation: Use to track validation processes of VNFs and NSDs </li> <li>VPN Credentials/Access: Used for requesting VPN Credentials/Access </li> </ul> <p>Also in the 'Main Site Operations' product, a version named 'unspecified' must be created.</p>"},{"location":"deploymentCompose/#5-configure-osportalapi-container-nfv-services-conditional","title":"5. Configure osportalapi container (NFV services) (conditional)","text":"<p>Change the respective fields: </p> <ul> <li>If you made changes to mysql and keycloak credentials.</li> <li>If you want to change logging level (TRACE / DEBUG / INFO / WARN / ERROR).</li> </ul> <p>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.</p> <p>In folder <code>org.etsi.osl.main/compose/</code> edit the file <code>docker-compose.yaml</code></p> <pre><code>SPRING_APPLICATION_JSON: '{\n \"spring.datasource.username\":\"root\",\n \"spring.datasource.password\":\"letmein\",\n \"spring-addons.issuers[0].uri\": \"http://keycloak:8080/auth/realms/openslice\",\n \"spring.security.oauth2.resourceserver.jwt.issuer-uri\": \"http://keycloak:8080/auth/realms/openslice\",\n \"springdoc.oAuthFlow.authorizationUrl\": \"http://keycloak:8080/auth/realms/openslice/protocol/openid-connect/auth\",\n \"springdoc.oAuthFlow.tokenUrl\": \"http://keycloak:8080/auth/realms/openslice/protocol/openid-connect/token\", \n \"spring.portal.main.domain\": \"http://localhost\",\n \"logging.level.org.springframework\" : \"INFO\"\n}'\n</code></pre>"},{"location":"deploymentCompose/#6-osscapi-container-tmf-api-service-conditional","title":"6. osscapi container (TMF API service) (conditional)","text":"<p>Change the respective fields: </p> <ul> <li>If you made changes to mysql and keycloak credentials.</li> <li>If you want to change logging level (TRACE / DEBUG / INFO / WARN / ERROR).</li> </ul> <p>If you are using a non-local domain, replace everywhere the http://keycloak:8080 with the respective {{protocol://domain.name}}.</p> <p>In folder <code>org.etsi.osl.main/compose/</code> edit the file <code>docker-compose.yaml</code></p> <pre><code>SPRING_APPLICATION_JSON: '{\n \"spring.datasource.username\":\"root\",\n \"spring.datasource.password\":\"letmein\",\n \"spring-addons.issuers[0].uri\": \"http://keycloak:8080/auth/realms/openslice\",\n \"spring.security.oauth2.resourceserver.jwt.issuer-uri\": \"http://keycloak:8080/auth/realms/openslice\",\n \"springdoc.oAuthFlow.authorizationUrl\": \"http://keycloak:8080/auth/realms/openslice/protocol/openid-connect/auth\",\n \"springdoc.oAuthFlow.tokenUrl\": \"http://keycloak:8080/auth/realms/openslice/protocol/openid-connect/token\", \n \"logging.level.org.springframework\" : \"INFO\"\n}'\n</code></pre>"},{"location":"deploymentCompose/#configure-nginx","title":"Configure nginx","text":"<p>In folder <code>org.etsi.osl.main/compose/nginx</code> create a configuration specific <code>nginx.conf</code> file.</p> <pre><code>cd org.etsi.osl.main/compose/nginx/\n</code></pre> <pre><code>sudo cp nginx.conf.default nginx.conf\n</code></pre> <p>If needed, in the nginx.conf file, edit the server_name for an non-local deployment.</p>"},{"location":"deploymentCompose/#configure-web-ui","title":"Configure Web UI","text":"<p>In folder <code>org.etsi.osl.portal.web/src/js/</code> create a configuration specific <code>config.js</code> file.</p> <pre><code>cd org.etsi.osl.portal.web/src/js\n</code></pre> <pre><code>sudo cp config.js.default config.js\n</code></pre> <p>Edit the <code>config.js</code> file with the information of your domain. <code>ROOTURL</code> will automatically extract the the Origin (Protocol://Domain:Port) of the deployment, but you must change <code>APIURL</code> property, if you are not aiming for a localhost installation, e.g. \"https://portal.openslice.io\".</p> <p>Example file:</p> <pre><code>{ \n BUGZILLA: \"ROOTURL/bugzilla/\",\n STATUS: \"ROOTURL/status/\",\n APIURL: \"http://localhost\",\n WEBURL: \"ROOTURL/nfvportal\",\n APIOAUTHURL: \"ROOTURL/auth/realms/openslice\",\n APITMFURL: \"ROOTURL/tmf-api/serviceCatalogManagement/v4\"\n}\n</code></pre>"},{"location":"deploymentCompose/#configure-tmf-web-ui","title":"Configure TMF Web UI","text":"<p>In the folder <code>org.etsi.osl.tmf.web/src/assets/config</code> there are 3 files available for configuration:</p> <ul> <li>config.prod.json (Basic information + API configuration)</li> <li>theming.scss (CSS color palette theming)</li> <li>config.theming.json (HTML configuration - Logo, Favicon, Footer)</li> </ul> <p>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 <code>org.etsi.osl.tmf.web/src/assets/config</code> directory as a copy of the default ones from the remote repository.</p> <p>Ensure that you check the <code>config.prod.json</code> and <code>theming.scss</code> files and readjust to your deployment if needed.</p> <pre><code># Starting from the root project directory\ncd org.etsi.osl.tmf.web/src/assets/config\n</code></pre> <p>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.</p> <p>Example file:</p> <pre><code>{ \n \"TITLE\": \"OpenSlice by ETSI\",\n \"PORTALVERSION\":\"2024Q2\",\n \"WIKI\": \"https://osl.etsi.org/documentation\",\n \"BUGZILLA\": \"{BASEURL}/bugzilla/\",\n \"STATUS\": \"{BASEURL}/status/\",\n \"WEBURL\": \"{BASEURL}\",\n \"PORTAL_REPO_APIURL\": \"{BASEURL}/osapi\",\n \"ASSURANCE_SERVICE_MGMT_APIURL\": \"{BASEURL}/oas-api\",\n \"APITMFURL\": \"{BASEURL}/tmf-api\",\n \"OAUTH_CONFIG\" : {\n \"issuer\": \"{BASEURL}/auth/realms/openslice\",\n \"loginUrl\": \"{BASEURL}/auth/realms/openslice/protocol/openid-connect/auth\",\n \"tokenEndpoint\": \"{BASEURL}/auth/realms/openslice/protocol/openid-connect/token\",\n \"userinfoEndpoint\": \"{BASEURL}/auth/realms/openslice/protocol/openid-connect/userinfo\",\n \"redirectUri\": \"{BASEURL}/redirect\",\n \"logoutUrl\": \"{BASEURL}/auth/realms/openslice/protocol/openid-connect/logout\", \n \"postLogoutRedirectUri\": \"{BASEURL}\",\n\n \"responseType\": \"code\",\n \"oidc\": false,\n \"clientId\": \"osapiWebClientId\",\n \"dummyClientSecret\": \"secret\",\n\n \"requireHttps\": false,\n \"useHttpBasicAuth\": true,\n \"clearHashAfterLogin\": false,\n\n \"showDebugInformation\": true\n }\n}\n</code></pre> <p>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\".</p> <p>If further customization, apart from the default provided, is needed for branding (Logo, Footer) then <code>config.theming.json</code> needs to be created in io.openslice.tmf.web/src/assets/config directory, as follows:</p> <pre><code># Starting from the root project directory\ncd org.etsi.osl.tmf.web/src/assets/config\n</code></pre> <pre><code>sudo cp config.theming.default.json config.theming.json\n</code></pre> <p>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 <code>org.etsi.osl.tmf.web/dist/io-openslice-portal-web/assets/config</code> directory. Although, it is mandatory to also apply these changes to the <code>org.etsi.osl.tmf.web/src/assets/config</code> for persistancy, as after any future rebuild of OpenSlice the <code>/dist</code> 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 <code>org.etsi.osl.tmf.web/src/assets/config</code> and rebuild the application.</p>"},{"location":"deploymentCompose/#deploy-openslice-via-docker-compose","title":"Deploy OpenSlice via Docker Compose","text":"<p>After configuring the services, and editing the docker compose file accordingly, the docker compose instantiation command can be performed.</p> <pre><code># Starting from the root project directory\ncd org.etsi.osl.main/compose/\n</code></pre> <pre><code>sudo docker compose --profile prod down;sudo docker compose --profile prod up -d --build\n</code></pre> <p>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.</p>"},{"location":"deploymentCompose/#validating-deployments-and-container-monitoring","title":"Validating deployments and container monitoring","text":"<p>You can monitor containers' status with portainer at port 9000 (http://your-ip:9000).</p> <p>Initially, you may monitor the local machine at portainer.</p> <p>Please check that all containers are in running state.</p>"},{"location":"deploymentCompose/#post-installation-steps","title":"Post installation steps","text":"<p>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.</p>"},{"location":"deploymentCompose/#configure-keycloak-server","title":"Configure Keycloak server","text":"<p>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. </p> <ul> <li> <p>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) </p> </li> <li> <p>Navigate to Administration Console </p> </li> <li> <p>Login with the credentials from section Configure keycloak container. Default values are:</p> <ul> <li>user: admin and </li> <li>password: Pa55w0rd</li> </ul> </li> </ul> <p>if you are running in HTTP you will get a message: HTTPS required.</p> <p>To resolve this issue when running in HTTP: </p> <ul> <li>Select the master realm from top left corner</li> <li>Go to login Tab and select \"Require SSL\": None</li> <li>Repeat for realm Openslice</li> </ul> <p>If you are running in HTTPS, then \"Require SSL\" can be left unchanged to external requests.</p>"},{"location":"deploymentCompose/#1-configure-redirects","title":"1. Configure redirects","text":"<p>Navigate to realm Openslice > Clients > osapiWebClientId and change the Root URL to your domain. </p> <p>Also, insert your domain, e.g. http://example.org/*, at:</p> <ul> <li>Valid Redirect URIs</li> <li>Web Origins</li> </ul>"},{"location":"deploymentCompose/#2-configure-email","title":"2. Configure email","text":"<p>Keycloak allows new users to register. Subsequently, this will also allow new users to register to the OpenSlice portal.</p> <p>Navigate to realm Openslice > Realm Settings > Login Tab > check User registration, Verify email, Forgot password etc.</p> <p>Finally, enter the details of the mail server at the Email Tab.</p> <p>Email configuration is optional for test runs, but if not provided the above functionalities (e.g. external user registration) will not be possible.</p>"},{"location":"deploymentCompose/#3-add-an-openslice-admin-user","title":"3. Add an OpenSlice admin user","text":"<p>This step is mandatory so as to access the OpenSlice Web UI. To add an OpenSlice admin user you must:</p> <ul> <li>Navigate to realm Openslice > Users > Add user</li> <li>Set a password</li> <li>Upon creation, navigate to Role Mappings and add ADMIN to Assigned Roles list</li> </ul> <p>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.</p>"},{"location":"deploymentCompose/#keycloak-at-localhost","title":"Keycloak at localhost","text":"<p>This is an important step if you run Keycloak on localhost!</p> <p>1 - Edit your Hosts File, adding the line below</p> <p><code>127.0.0.1 keycloak</code></p> <p>Hosts File Location:</p> <ul> <li> <p>In Linux/Unix, the file's location is at /etc/hosts </p> </li> <li> <p>In Windows, its location is at c:\\Windows\\System32\\Drivers\\etc\\hosts</p> </li> </ul> <p>2 - Replace http://localhost/auth/ with http://keycloak:8080/auth/ in your Keycloak config for AngularJS and Angular (see examples below).</p> <p>Explanation</p> <p>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.</p> <p>2.1 - For the Angular configuration (TMF portal UI), navigate to org.etsi.osl.tmf.web/src/assets/config and edit config.prod.json</p> <pre><code># Starting from the root project directory\ncd org.etsi.osl.tmf.web/src/assets/config\n</code></pre> <pre><code>nano config.prod.json\n</code></pre> <p>After editing, the displayed properties should look like the example below:</p> <pre><code>{ \n \"OAUTH_CONFIG\" : {\n \"issuer\": \"http://keycloak:8080/auth/realms/openslice\",\n \"loginUrl\": \"http://keycloak:8080/auth/realms/openslice/protocol/openid-connect/auth\",\n \"tokenEndpoint\": \"http://keycloak:8080/auth/realms/openslice/protocol/openid-connect/token\",\n \"userinfoEndpoint\": \"http://keycloak:8080/auth/realms/openslice/protocol/openid-connect/userinfo\",\n \"redirectUri\": \"{BASEURL}/redirect\",\n \"logoutUrl\": \"http://keycloak:8080/auth/realms/openslice/protocol/openid-connect/logout\", \n \"postLogoutRedirectUri\": \"{BASEURL}\",\n }\n}\n</code></pre> <p>Note the difference in changing {BASEURL} -> http://keycloak:8080</p> <p>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</p> <p>2.2 - For the AngularJS configuration (NVF portal UI), navigate to org.etsi.osl.portal.web/src/js and edit config.js</p> <pre><code># Starting from the root project directory\ncd org.etsi.osl.portal.web/src/js\n</code></pre> <pre><code>nano config.js\n</code></pre> <p>After editing, the displayed properties should look like the example below:</p> <pre><code>var appConfig = angular.module('portalwebapp.config',[]);\n\n\nappConfig.factory('APIEndPointService', function() {\n return { \n APIOAUTHURL: \"http://keycloak:8080/auth/realms/openslice\",\n };\n});\n</code></pre> <p>Note the difference in \"APIOAUTHURL\" property, changing ROOTURL -> http://keycloak:8080</p>"},{"location":"deploymentCompose/#nfv-orchestrator-configuration","title":"NFV Orchestrator Configuration","text":"<p>After successfully deploying and configuring OpenSlice, you may configure its environment (e.g. the NFVO) that will facilitate the deployment of NFV artifacts.</p> <p>See NFV Orchestrator Configuration.</p>"},{"location":"deploymentK8s/","title":"OpenSlice Deployment Guide with Kubernetes","text":""},{"location":"deploymentK8s/#intended-audience-openslice-administrators","title":"Intended Audience: OpenSlice administrators","text":"<p>This is WIP.</p> <p>Please refer to this guide.</p>"},{"location":"etsi_osl/","title":"The ETSi SDG OSL","text":"<p>OpenSlice is developed by the OSL ETSI Software Development Group see more info</p>"},{"location":"history/","title":"History","text":""},{"location":"history/#history","title":"History","text":"<ul> <li>The NFV portal part of OpenSlice was initially developed in H2020 European Research project 5GinFIRE by University of Patras, Greece</li> <li>OpenSlice core services, APIs was further developed and maintained in H2020 European project 5G-VINNI by University of Patras, Greece</li> <li>OpenSlice has been a part of OSM's OSS/BSS ecosystem</li> <li>OpenSlice is now an ETSI SDG Group since 2023</li> </ul>"},{"location":"history/#citation","title":"Citation","text":"<p>Please cite our ![paper] if you use OpenSlice in your research</p> <pre><code>\n@misc{tranoris2021openslice,\n title={Openslice: An opensource OSS for Delivering Network Slice as a Service}, \n author={Christos Tranoris},\n year={2021},\n eprint={2102.03290},\n archivePrefix={arXiv},\n primaryClass={cs.NI}\n}\n\n\n</code></pre>"},{"location":"nfvoconfig/","title":"NFV Orchestrator configuration","text":"<p>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.</p> <p>Configuration of your target(s) NFVOs/MANO services with Openslice is performed through the NFV portal.</p> <ol> <li> <p>Login to {{yourdomain}}/nfvportal/</p> </li> <li> <p>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.</p> </li> <li> <p>Navigate to Admin > Manage MANO providers > Add New MANO Provider and enter its details:</p> <ul> <li>Name and description of your choice. The selected name will supplement the NFV artifacts of this provider.</li> <li>One of the already defined MANO platforms</li> <li>API URL Endpoint, eg: https://10.10.10.10:9999 (This is the SOL005 NBI endpoint - Note the port 9999)</li> <li>Username, Password and Project of your OSM tenant.</li> </ul> </li> </ol> <p>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).</p> <p>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). </p> <p>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 <code>OSM_PRESENT</code>. If during this process, an artifact is deleted from the MANO, the respective status field will be updated to <code>OSM_MISSING</code>.</p>"},{"location":"portals_intro/","title":"OpenSlice Portals","text":"<p>Openslice comprises of a web landing page See Demo that navigates to the respective Portal:</p> <ul> <li>Services Portal See Demo</li> <li>NFV Portal See Demo</li> <li>Products Portal See Demo</li> <li>Testing Portal See Demo</li> <li>Resources Portal See Demo</li> </ul> <p>Following you may find the scope each portal focuses on and the main TMF APIs it supports.</p> <p>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.</p> <p>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</p> <p>More information can be found at NFV Services.</p> <p>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.</p> <p>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.</p> TMF620 TMF632 TMF633 TMF634 TMF638 TMF639 TMF640 TMF641 TMF642 TMF653 TMF685 Services Portal x x x x x x Products Portal x x Testing Portal x x Resources Portal x x x x <p>The NFV Portal uses a proprietary API</p>"},{"location":"role_keycloak_management/","title":"Role management in Keycloak","text":"<p>Some initial configuration of Keycloak happens at Installation/Deployment time. Here are some notes regarding user management</p>"},{"location":"role_keycloak_management/#intended-audience-openslice-administrators","title":"Intended Audience: OpenSlice administrators","text":"<p>There are cases that OpenSlice administrators need to configure Keycloak:</p> <ul> <li>Change user roles, e.g. make a Simple user a Service Designer</li> <li>Domain management</li> <li>User Password reset</li> </ul>"},{"location":"terminology/","title":"User Roles","text":"<ul> <li>User</li> <li>Service Designer</li> <li>OpenSlice administrator</li> </ul>"},{"location":"terminology/#terms","title":"Terms","text":"<ul> <li>Resource Facing Service Specification (RFSSpec): A Service that exposes a resource Specification as a Service.</li> <li>Customer Facing Service Specification (CFSSpec): Service exposed to users for Service Orders. Usually it exposes other CFSSpec(Service Bundle) or other RFSSpecs</li> <li>OpenSlice management cluster</li> <li>Service Specification: Detailed descriptions of services, including attributes, configurations, performance metrics, and SLAs.</li> <li>Service Catalog</li> <li>Service Categories</li> <li>Service Inventory</li> </ul>"},{"location":"under_construction/","title":"Under construction","text":"<p>under construction</p>"},{"location":"architecture/architecture/","title":"Architecture","text":"<p>Openslice offers the following main functionalities:</p> <ul> <li>Service Catalog Management: A CSP will have the ability to manage the Service Catalog Items, their attributes , organize in categories and decide what to make available to Customers</li> <li>Services Specifications: A CSP will be able to manage Service Specifications</li> <li>Service Catalog Exposure: A CSP will be able to expose catalog to customers and related parties</li> <li>Service Catalog to Service Catalog: Openslice able to consume and provide Service Catalog items to other catalogs</li> <li>Service Order: The Customer will be able to place a Service Order</li> <li>Service Inventory: The Customer and Provider will be able to view deployed Services status</li> </ul> <p>The following figure displays the overall architecture of Openslice.</p> <p></p> <p>Openslice allows Vertical Customers browsing the available offered service specifications. It consists of:</p> <ul> <li>Web frontend UIs that consist of mainly two portals: i) a NFV portal allowing users self-service management and onboarding VNFDs/NSDs to facility\u2019s NFVO ii) a Services Portal, which allows users to browse the Service Catalog, Service Blueprints specifications and the Service Inventory</li> <li>An API gateway that proxies the internal APIs and used by the web front end as well as any other 3rd party service</li> <li>A Message Bus where all microservices use it to exchange messages either via message queues or via publish/subscribe topics</li> <li>An authentication server implementing Oauth2 authentication scheme</li> <li>A microservice offering TMF compliant API services (eg Service Catalog API, Service Ordering APIetc)</li> <li>A microservice offering NFV API services (eg VNF/NSD onboarding etc) and allows to store VNFDs and NSDs in a catalog</li> <li>A microservice that is capable to interface to an issue management system. For example it raises an issue to all related stakeholders (CSP, NOP, CSC) that a new Service Order is requested</li> <li>Central logging microservice that is capable to log all distributed actions in to an Elasticsearch cluster</li> <li>A Service Orchestrator solution that will propagate Service Ordering requests to the equivalent SOs and NFVOs </li> </ul> <p>The following figure depicts how Openslice microservices are deployed</p> <p></p>"},{"location":"architecture/architecture/#deploying-openslice-in-multi-domain-scenarios","title":"Deploying Openslice in multi domain scenarios","text":"<p>A typical deployment across domains, involves today some typical components: i) an OSS/BSS to allow customers access the service catalog and perform service orders, ii) a Service Orchestrator (SO) component for executing the service order workflow, as well as iii) a Network Functions Virtualization Orchestrator (NFVO) for configuring the iv) network resources.</p> <p>TMF Open APIs are introduced not only for exposing catalogues and accepting service orders, but also implementing the East-West interfaces between the domains, fulfilling also the LSO requirements as introduced by MEF.</p> <p>The following figure shows how openslice could be used in such scenarios:</p> <p></p> <p>See more Consuming Services From External Partner Organizations</p>"},{"location":"architecture/centrallog/","title":"Central Logging","text":"<p>Openslice follows the centralized log management concept, i.e. a type of logging solution system that consolidates the log data from different services and pushes it to a central, accessible and easy-to-use interface. </p> <p>For that reason, Elasticsearch is elected as an open-source centralized logging solution for collecting, parsing and storing logs towards a real-time data analytics tool that provides insights from any type of structured and unstructured data source.</p>"},{"location":"architecture/consumingServicesFromExternalPartners/","title":"Consuming Services From External Partner Organizations","text":"<p>A typical deployment across domains, involves today some typical components: i) an OSS/BSS to allow customers access the service catalog and perform service orders, ii) a Service Orchestrator (SO) component for executing the service order workflow, as well as iii) a Network Functions Virtualization Orchestrator (NFVO) for configuring the iv) network resources.</p> <p>TMF Open APIs are introduced not only for exposing catalogues and accepting service orders, but also implementing the East-West interfaces between the domains, fulfilling also the LSO requirements as introduced by MEF.</p> <p>The following figure shows how openslice could be used in such scenarios:</p> <p></p> <p>In Openslice we can consume services from 3rd parties via Open APIs.</p> <p>We use the TMF 632 Party Management model to specify Organizations that we can exchange items and other information such as:</p> <ul> <li>Import Service Specifications</li> <li>Create a Service Order</li> <li>Use the Service Inventory to query the status of the service ordered to the external partner organization</li> </ul>"},{"location":"architecture/consumingServicesFromExternalPartners/#define-an-organization-as-3rd-party-to-consume-services-east-west","title":"Define an Organization as 3rd party to consume services East-West","text":"<p>An organization must have the following characteristics in openslice catalog, like for example:</p> <p>\"EXTERNAL_TMFAPI_BASEURL\", \"http://portal.openslice.io\"</p> <p>\"EXTERNAL_TMFAPI_CLIENTREGISTRATIONID\", \"authOpensliceProvider\"</p> <p>\"EXTERNAL_TMFAPI_OAUTH2CLIENTID\", \"osapiWebClientId\"</p> <p>\"EXTERNAL_TMFAPI_OAUTH2CLIENTSECRET\", \"secret\"</p> <p>\"EXTERNAL_TMFAPI_OAUTH2SCOPES\", scopes</p> <p>\"EXTERNAL_TMFAPI_OAUTH2TOKENURI\", \"http://portal.openslice.io/osapi-oauth-server/oauth/token\"</p> <p>\"EXTERNAL_TMFAPI_USERNAME\", \"admin\"</p> <p>\"EXTERNAL_TMFAPI_PASSWORD\", \"openslice\"</p> <p>\"EXTERNAL_TMFAPI_SERVICE_CATALOG_URLS\" = \"/tmf-api/serviceCatalogManagement/v4/serviceSpecification?type=CustomerFacingServiceSpecification\" (this is optional, fetch a list of service specs it will be relative with the BASEURL. If the url is empty then no specs will be fetched, the EXTERNAL_TMFAPI_SERVICE_CATEGORY_URLS might be used)</p> <p>\"EXTERNAL_TMFAPI_SERVICE_CATEGORY_URLS\" = \"/tmf-api/serviceCatalogManagement/v4/serviceCategory/{categoryid}\" (this example will fetch all specs in a category. You may define comma separated URLs of categories API URL . This will fetch specifications of every defined category. If you want only one specific category put for example the uuid only of one category: \"/tmf-api/serviceCatalogManagement/v4/serviceCategory/bda02821-bc4d-4bd6-b64b-d9c2aa5f8e6d\". multiple urls should be \"/tmf-api/serviceCatalogManagement/v4/serviceCategory/bda02821-bc4d-4bd6-b64b-d9c2aa5f8e6d,/tmf-api/serviceCatalogManagement/v4/serviceCategory/9b6d8bf3-abd2-43c4-8154-c8c6fe5545b2\")</p> <p>\"EXTERNAL_TMFAPI_SERVICE_SPEC\" = \"/tmf-api/serviceCatalogManagement/v4/serviceSpecification\"</p> <p>\"EXTERNAL_TMFAPI_SERVICE_ORDER_URLS\"= \"/test/v1/serviceorder\" (this is optional)</p> <p>An example Organization defined example in json:</p> <pre><code>\n{\n \"uuid\": \"1a09a8b5-6bd5-444b-b0b9-a73c69eb42ae\",\n \"@baseType\": \"BaseEntity\",\n \"@schemaLocation\": null,\n \"@type\": null,\n \"href\": null,\n \"name\": \"Openslice.io\",\n \"id\": \"1a09a8b5-6bd5-444b-b0b9-a73c69eb42ae\",\n \"isHeadOffice\": null,\n \"isLegalEntity\": null,\n \"nameType\": null,\n \"organizationType\": null,\n \"tradingName\": null,\n \"contactMedium\": [],\n \"creditRating\": [],\n \"existsDuring\": null,\n \"externalReference\": [],\n \"organizationChildRelationship\": [],\n \"organizationIdentification\": [],\n \"organizationParentRelationship\": null,\n \"otherName\": [],\n \"partyCharacteristic\": [\n {\n \"uuid\": \"3a2f7221-e0a2-4a6b-88d1-534c8e1963f6\",\n \"@baseType\": \"BaseEntity\",\n \"@schemaLocation\": null,\n \"@type\": null,\n \"href\": null,\n \"name\": \"EXTERNAL_TMFAPI_CLIENTREGISTRATIONID\",\n \"valueType\": null,\n \"value\": {\n \"value\": \"authOpensliceProvider\",\n \"alias\": null\n }\n },\n {\n \"uuid\": \"c24bb527-f178-4d38-9b93-2027c1732876\",\n \"@baseType\": \"BaseEntity\",\n \"@schemaLocation\": null,\n \"@type\": null,\n \"href\": null,\n \"name\": \"EXTERNAL_TMFAPI_USERNAME\",\n \"valueType\": null,\n \"value\": {\n \"value\": \"admin\",\n \"alias\": null\n }\n },\n {\n \"uuid\": \"27e45df8-414b-44c6-a5d5-3f064e2cfd3b\",\n \"@baseType\": \"BaseEntity\",\n \"@schemaLocation\": null,\n \"@type\": null,\n \"href\": null,\n \"name\": \"EXTERNAL_TMFAPI_PASSWORD\",\n \"valueType\": null,\n \"value\": {\n \"value\": \"openslice\",\n \"alias\": null\n }\n },\n {\n \"uuid\": \"e0e470b8-6024-4014-8a18-2333e5465ce1\",\n \"@baseType\": \"BaseEntity\",\n \"@schemaLocation\": null,\n \"@type\": null,\n \"href\": null,\n \"name\": \"EXTERNAL_TMFAPI_OAUTH2CLIENTSECRET\",\n \"valueType\": null,\n \"value\": {\n \"value\": \"secret\",\n \"alias\": null\n }\n },\n {\n \"uuid\": \"3e0de762-ac80-4c1e-a0a1-f265ff0899b4\",\n \"@baseType\": \"BaseEntity\",\n \"@schemaLocation\": null,\n \"@type\": null,\n \"href\": null,\n \"name\": \"EXTERNAL_TMFAPI_OAUTH2SCOPES\",\n \"valueType\": null,\n \"value\": {\n \"value\": \"admin;read\",\n \"alias\": null\n }\n },\n {\n \"uuid\": \"0bbb8314-f7f2-420d-9fed-ba054b15f886\",\n \"@baseType\": \"BaseEntity\",\n \"@schemaLocation\": null,\n \"@type\": null,\n \"href\": null,\n \"name\": \"EXTERNAL_TMFAPI_OAUTH2TOKENURI\",\n \"valueType\": null,\n \"value\": {\n \"value\": \"http://portal.openslice.io/osapi-oauth-server/oauth/token\",\n \"alias\": null\n }\n },\n {\n \"uuid\": \"3a567de4-79eb-4006-a500-3e5229b44175\",\n \"@baseType\": \"BaseEntity\",\n \"@schemaLocation\": null,\n \"@type\": null,\n \"href\": null,\n \"name\": \"EXTERNAL_TMFAPI_OAUTH2CLIENTID\",\n \"valueType\": null,\n \"value\": {\n \"value\": \"osapiWebClientId\",\n \"alias\": null\n }\n },\n {\n \"uuid\": \"6dca729f-dbe1-46b7-89f1-5c4f9fe89d4e\",\n \"@baseType\": \"BaseEntity\",\n \"@schemaLocation\": null,\n \"@type\": null,\n \"href\": null,\n \"name\": \"EXTERNAL_TMFAPI_BASEURL\",\n \"valueType\": null,\n \"value\": {\n \"value\": \"http://portal.openslice.io\",\n \"alias\": null\n }\n }\n ],\n \"relatedParty\": [],\n \"status\": null,\n \"taxExemptionCertificate\": []\n}\n\n</code></pre>"},{"location":"architecture/issuemgt/","title":"Issue Management","text":"<p>For issue management support, Openslice relies on Bugzilla. Bugzilla is a ticketing tool that allows issue reporting and tracking via tickets to all relevant stakeholders. </p> <p>The figure below displays the overall issue management service architecture integrating Bugzilla as its core and how this tool interacts with other Openslice services presenting some distinctive scenarios. It should be noted that Bugzilla tickets will not only be used for bugs/errors, but also for general requests, e.g. Service Order procedure.</p> <p></p>"},{"location":"architecture/messagebus/","title":"Message Bus and exchanged Messages","text":"<p>Openslice has a Message bus which allows Openslice services to exchange messages via queues and topics.</p> <p>It is based on ActiveMQ.</p> <p>3rd party services can be attached to bus and subscribe to message topics or request resources via queues.</p>"},{"location":"architecture/messagebus/#queue-messages","title":"QUEUE MESSAGES","text":"Message Alias CATALOG_GET_SERVICEORDERS Name jms:queue:CATALOG.GET.SERVICEORDERS Type queue Destination TMF API service Producers OSOM Body Description Return a List as String Json Message Alias CATALOG_GET_SERVICEORDER_BY_ID Name jms:queue:CATALOG.GET.SERVICEORDER_BY_ID Type queue Destination TMF API service Producers OSOM Body String orderid Description Return a ServiceOrder as String Json Message Alias CATALOG_UPD_SERVICEORDER_BY_ID Name jms:queue:CATALOG.UPD.SERVICEORDER_BY_ID Type queue Destination TMF API service Producers OSOM Body ServiceOrderUpdate serviceOrder Headers \"orderid\"= orderid Description Returns a ServiceOrder as String Message Alias CATALOG_GET_SERVICESPEC_BY_ID Name jms:queue:CATALOG.GET.SERVICESPEC_BY_ID Type queue Destination TMF API service Producers OSOM Body specid Description Return a ServiceSpecification Message Alias CATALOG_ADD_SERVICESPEC Name jms:queue:CATALOG.ADD.SERVICESPEC Type queue Destination TMF API service Producers CRIDGE Body ServiceSpecCreate Description Creates a ServiceSpecification and returns a ServiceSpecification as String Message Alias CATALOG_UPD_SERVICESPEC Name jms:queue:CATALOG.UPD.SERVICESPEC Type queue Destination TMF API service Producers CRIDGE Body ServiceSpecUpdate Headers \"serviceSpecid\" = serviceSpecId Description Updates a ServiceSpecification and returns a ServiceSpecification as String. --- Message Alias CATALOG_UPDADD_SERVICESPEC Name jms:queue:CATALOG.UPDADD.SERVICESPEC Type queue Destination TMF API service Producers CRIDGE Body ServiceSpecUpdate Headers \"serviceSpecid\" = serviceSpecId, \"forceId\"=forceId Description Updates a ServiceSpecification and returns a ServiceSpecification as String. If forceId is true then tries to assign the requested ID to the spec Message Alias CATALOG_ADD_SERVICEORDER Name jms:queue:CATALOG.ADD.SERVICEORDER Type queue Destination TMF API service Producers OSOM Body ServiceOrderCreate serviceOrder Headers Description Creates a ServiceOrder and returns a ServiceOrder as String Message Alias CATALOG_GET_INITIAL_SERVICEORDERS_IDS Name jms:queue:CATALOG.GET.INITIAL_SERVICEORDERS Type queue Destination TMF API service Producers Body Description Return a List as String Json Message Alias CATALOG_GET_SERVICEORDER_IDS_BY_STATE Name jms:queue:CATALOG.GET.ACKNOWLEDGED_SERVICEORDERS Type queue Destination TMF API service Producers OSOM Body Headers \"orderstate\"= orderState Description String Json ArrayList of ServiceOrders Message Alias CATALOG_ADD_SERVICE Name jms:queue:CATALOG.ADD.SERVICE Type queue Destination TMF API service Producers OSOM Body ServiceCreate String json Headers \"orderid\"=orderid, \"serviceSpecid\"= specid Description Creates Service based an a Service Spec, Returns a Service object Message Alias CATALOG_UPD_SERVICE Name jms:queue:CATALOG.UPD.SERVICE Type queue Destination TMF API service Producers Body ServiceUpdate Headers \"serviceid\" = serviceId, \"propagateToSO\" = true/false Description will update a service by id and return the service instance. If propagateToSO=true then any service change will be handled by OSOM. This is needed to be controlled in order to avoid update loops Message Alias CATALOG_GET_SERVICE_BY_ID Name jms:queue:CATALOG.GET.SERVICE Type queue Destination TMF API service Producers OSOM Body String serviceID Description returns a Service instance <p>---| Message | | | ------------- |----------------| |Alias | CATALOG_GET_SERVICE_BY_ORDERID | |Name | jms:queue:CATALOG.GET.SERVICE_BY_ORDERID | |Type | queue | |Destination | TMF API service | |Producers | | |Body | String serviceID | |Description | returns Service IDs of a specific order given then order id |</p> Message Alias CATALOG_SERVICE_QUEUE_ITEMS_GET Name jms:queue:CATALOG.SERVICEQUEUEITEMS.GET Type queue Destination TMF API service Producers OSOM Body Description returns a LIST OF Service Queue Items --- Message Alias CATALOG_SERVICE_QUEUE_ITEM_UPD Name jms:queue:CATALOG.SERVICEQUEUEITEM.UPDATE Type queue Destination TMF API service Producers OSOM Body String SERVICEQUEUEITEM Headers \"itemid\" = SERVICEQUEUEITEM id Description ill update a service queue item by id and return the instance --- Message Alias CATALOG_SERVICE_QUEUE_ITEM_DELETE Name jms:queue:CATALOG.SERVICEQUEUEITEM.DELETE Type queue Destination TMF API service Producers OSOM Body Headers \"itemid\" = SERVICEQUEUEITEM id Description ill delete a service queue item by id Message Alias CATALOG_SERVICES_TO_TERMINATE Name jms:queue:CATALOG.GET.SERVICETOTERMINATE Type queue Destination TMF API service Producers OSOM Body Headers Description Get a list of ACTIVE services with END DAte in the past --- Message Alias CATALOG_SERVICES_OF_PARTNERS Name jms:queue:CATALOG.GET.SERVICESOFPARTNERS Type queue Destination TMF API service Producers OSOM Body Headers Description Get a list of ACTIVE services from the inventory of partners Message Alias NFV_CATALOG_GET_NSD_BY_ID Name jms:queue:NFVCATALOG.GET.NSD_BY_ID Type queue Destination NFV Catalog service Producers TMF API, OSOM Body NSDid Description Returns a NetworkServiceDescriptor object Message Alias NFV_CATALOG_DEPLOY_NSD_REQ Name jms:queue:NFVCATALOG.DEPLOY.NSD_REQ Type queue Destination NFV Catalog service Producers OSOM Body DeploymentDescriptor as Json String Headers NSD id Description Returns a DeploymentDescriptor object as json string containing deployment info Message Alias NFV_CATALOG_UPD_DEPLOYMENT_BY_ID Name jms:queue:NFVCATALOG.UPD.DEPLOYMENT_BY_ID Type queue Destination NFV Catalog service Producers OSOM Body DeploymentDescriptor as Json String Headers DeploymentDescriptor id Description Updates and Returns a DeploymentDescriptor object as json string containing deployment info Message Alias GET_USER_BY_USERNAME Name jms:queue:GET.USER_BY_USERNAME Type queue Destination NFV Catalog service (this is temproary for now) Producers TMF API Body username Headers Description Returns a PortalUser object as json string containing user info Message Alias NFV_CATALOG_GET_DEPLOYMENT_BY_ID Name jms:queue:NFVCATALOG.GET.DEPLOYMENT_BY_ID Type queue Destination NFV Catalog service Producers OSOM Body Deployment ID Description Returns a DeploymentDescriptor object Message Alias CATALOG_GET_EXTERNAL_SERVICE_PARTNERS Name jms:queue:CATALOG.GET.EXTERNALSERVICEPARTNERS Type queue Destination TMF API service Producers OSOM Body Headers Description As a String Json ArrayList of Organizaton objects containing the characteristic name EXTERNAL_TMFAPI Message Alias CATALOG_UPD_EXTERNAL_SERVICESPEC Name jms:queue:CATALOG.UPD.EXTERNAL_SERVICESPEC Type queue Destination TMF API service Producers OSOM or maybe used by others that would like to update a Service Spec Body A serviceSpecification as json string Headers servicespecification id, orgid id Description Updates (or inserts if does not exist in catalog) an external service specification) Message Alias NFV_CATALOG_NSACTIONS_SCALE Name jms:queue:NSACTIONS.SCALE Type queue Destination TMF API service Producers OSOM or maybe used by others that would like scale a NS Body A ScaleDescriptor as json string Headers none Description performs a scale Message Alias NFV_CATALOG_NS_LCMCHANGED Name NFV_CATALOG_NS_LCMCHANGED Type topic Destination any Producers MANO client Body A json string Headers none Description A NFV_CATALOG_NS_LCMCHANGED message is published when LCM of a running NS is changed"},{"location":"architecture/messagebus/#alarms","title":"ALARMS","text":"Message Alias ALARMS_ADD_ALARM Name jms:queue:ALARMS.ADD.ALARM Type queue Publishers Consumers TMF API Body AlarmCreate Headers Description Add an alarm Message Alias ALARMS_UPDATE_ALARM Name jms:queue:ALARMS.UPDATE.ALARM Type queue Publishers Consumers TMF API Body AlarmUpdate Headers alarmid = alarm id, body (AlarmUpdate object) Description Update an alarm Message Alias ALARMS_GET_ALARM Name jms:queue:ALARMS.GET.ALARM Type queue Publishers Consumers TMF API Body Headers alarmid = alarm id Description get an alarm"},{"location":"architecture/messagebus/#event-topics-in-message-bus","title":"EVENT TOPICS IN Message Bus","text":"Message Alias EVENT_SERVICE_CREATE Name jms:topic:EVENT.SERVICE.CREATE Type topic Publishers TMF API Consumers - Body Notification object Headers \"eventid\"=eventid, \"objId\"= objId Description xx Message Alias EVENT_SERVICE_STATE_CHANGED Name jms:topic:EVENT.SERVICE.STATECHANGED Type topic Publishers TMF API Consumers - Body Notification object Headers \"eventid\"=eventid, \"objId\"= objId Description xx Message Alias EVENT_SERVICE_DELETE Name jms:topic:EVENT.SERVICE.DELETE Type topic Publishers TMF API Consumers - Body Notification object. Can be one of ServiceOrderCreateNotification, ServiceOrderStateChangeNotification, ServiceOrderAttributeValueChangeNotification, ServiceOrderDeleteNotification, etc Headers \"eventid\"=eventid, \"objId\"= objId Description xx Message Alias EVENT_SERVICE_ATTRIBUTE_VALUE_CHANGED Name jms:topic:EVENT.SERVICE.ATTRCHANGED Type topic Publishers TMF API Consumers - Body Notification object. Can be one of ServiceOrderCreateNotification, ServiceOrderStateChangeNotification, ServiceOrderAttributeValueChangeNotification, ServiceOrderDeleteNotification, etc Headers \"eventid\"=eventid, \"objId\"= objId Description xx Message Alias EVENT_SERVICE_ORDER_CREATE Name jms:topic:EVENT.SERVICEORDER.CREATE Type topic Publishers TMF API Consumers BUGZILLA Service, CentralLog Service Body Notification object. Can be one of ServiceOrderCreateNotification, ServiceOrderStateChangeNotification, ServiceOrderAttributeValueChangeNotification, ServiceOrderDeleteNotification, etc Headers \"eventid\"=eventid, \"objId\"= objId Description The Event of the Notification object contains the ServiceOrder object. Bugzilla service for example uses this to create a new issue Message Alias EVENT_SERVICE_ORDER_STATE_CHANGED Name jms:topic:EVENT.SERVICEORDER.STATECHANGED Type topic Publishers TMF API Consumers BUGZILLA Service, CentralLog Service Body Notification object. Can be one of ServiceOrderCreateNotification, ServiceOrderStateChangeNotification, ServiceOrderAttributeValueChangeNotification, ServiceOrderDeleteNotification, etc Headers \"eventid\"=eventid, \"objId\"= objId Description The Event of the Notification object contains the ServiceOrder object. Bugzilla service for example uses this to update an issue Message Alias EVENT_SERVICE_ORDER_DELETE Name jms:topic:EVENT.SERVICEORDER.DELETE Type topic Publishers TMF API Consumers BUGZILLA Service, CentralLog Service Body Notification object. Can be one of ServiceOrderCreateNotification, ServiceOrderStateChangeNotification, ServiceOrderAttributeValueChangeNotification, ServiceOrderDeleteNotification, etc Headers \"eventid\"=eventid, \"objId\"= objId Description The Event of the Notification object contains the ServiceOrder object Message Alias EVENT_SERVICE_ORDER_ATTRIBUTE_VALUE_CHANGED Name jms:topic:EVENT.SERVICEORDER.ATTRCHANGED Type topic Publishers TMF API Consumers BUGZILLA Service, CentralLog Service Body Notification object. Can be one of ServiceOrderCreateNotification, ServiceOrderStateChangeNotification, ServiceOrderAttributeValueChangeNotification, ServiceOrderDeleteNotification, etc Headers \"eventid\"=eventid, \"objId\"= objId Description The Event of the Notification object contains the ServiceOrder object Message Alias EVENT_ALARM_CREATE Name jms:topic:EVENT.ALARM.CREATE Type topic Publishers TMF API Consumers OAS, BUGZILLA Service, CentralLog Service Body AlarmCreateEvent Headers Description The Event contains the Alarm object in payload Message Alias CATALOG_ADD_RESOURCE Name jms:queue:CATALOG.ADD.RESOURCE Type topic Publishers TMF API Consumers any Body ResourceCreate Headers Description The Body contains the ResourceCreate object to add Message Alias CATALOG_UPD_RESOURCE Name jms:queue:CATALOG.UPD.RESOURCE Type topic Publishers TMF API Consumers any Body ResourceUpdate Headers resourceid , propagateToSO Description The Body contains the ResourceCreate object to update Message Alias CATALOG_GET_RESOURCE_BY_ID Name jms:queue:CATALOG.GET.RESOURCE Type topic Publishers TMF API Consumers any Body resourceid Headers Description The Body contains the ResourceCreate object to update Message Alias CATALOG_RESOURCES_OF_PARTNERS Name jms:queue:CATALOG.GET.SERVICESOFPARTNERS Type topic Publishers TMF API Consumers any Body none Headers none Description retrieve all active services of partners Message Alias CATALOG_ADD_RESOURCESPEC Name jms:queue:CATALOG.ADD.RESOURCESPEC Type topic Publishers TMF API Consumers any Body ResourceSpecificationCreate Headers Description The Body contains the ResourceSpecificationCreate object to add Message Alias CATALOG_UPD_RESOURCESPEC Name jms:queue:CATALOG.UPD.RESOURCESPEC Type topic Publishers TMF API Consumers any Body ResourceSpecificationUpdate Headers resourceSpecId Description The Body contains the ResourceSpecificationCreate object to update Message Alias CATALOG_GET_RESOURCESPEC_BY_ID Name jms:queue:CATALOG.GET.RESOURCESPEC_BY_ID Type topic Publishers TMF API Consumers any Body resourceSpecid Headers Description The Body contains the object id to find Message Alias CATALOG_UPDADD_RESOURCESPEC Name jms:queue:CATALOG.UPDADD.RESOURCESPEC Type topic Publishers TMF API Consumers any Body resourceid Headers Description The Body contains the ResourceSpecificationCreate object to update or create if not exist Message Alias EVENT_RESOURCE_CREATE Name jms:topic:EVENT.RESOURCE.CREATE Type topic Publishers TMF API Consumers BUGZILLA Service, CentralLog Service, other Body Notification object. Headers \"eventid\"=eventid, \"objId\"= objId Description The Event of the Notification object contains the Resource object Message Alias EVENT_RESOURCE_STATE_CHANGED Name jms:topic:EVENT.RESOURCE.STATECHANGED Type topic Publishers TMF API Consumers BUGZILLA Service, CentralLog Service, other Body Notification object. Headers \"eventid\"=eventid, \"objId\"= objId Description The Event of the Notification object contains the Resource object Message Alias EVENT_RESOURCE_DELETE Name jms:topic:EVENT.SERVICE.RESOURCE Type topic Publishers TMF API Consumers BUGZILLA Service, CentralLog Service, other Body Notification object. Headers \"eventid\"=eventid, \"objId\"= objId Description The Event of the Notification object contains the Resource object Message Alias EVENT_RESOURCE_ATTRIBUTE_VALUE_CHANGED Name jms:topic:EVENT.RESOURCE.ATTRCHANGED Type topic Publishers TMF API Consumers BUGZILLA Service, CentralLog Service, other Body Notification object. Headers \"eventid\"=eventid, \"objId\"= objId Description The Event of the Notification object contains the Resource object Message Alias CATALOG_GET_LCMRULE_BY_ID Name jms:queue:CATALOG.GET.LCMRULE Type topic Publishers TMF API Consumers any Body lcmid Headers Description The Body contains the LCMRuleSpec object Message Alias CATALOG_GET_LCMRULES_BY_SPECID_PHASE Name jms:queue:CATALOG.GET.LCMRULES_BY_SPECID_PHASE Type topic Publishers TMF API Consumers any Body Headers header.servicespecid, header.phasename Description The Body contains the LCMRuleSpec objects of the specific Service Spec and the specific phase Message Alias CATALOG_GET_SERVICETESTSPEC_BY_ID Name jms:queue:CATALOG.GET.SERVICETESTSPEC_BY_ID Type queue Destination TMF API service Producers OSOM Body specid Description Return a ServiceTestSpecification Message Alias CATALOG_ADD_SERVICETEST Name jms:queue:CATALOG.ADD.SERVICETEST Type queue Destination TMF API service Producers OSOM Body ServiceTestCreate String json Headers \"orderid\"=orderid, \"serviceTestSpecid\"= specid Description Creates Service Test based an a Service Test Spec, Returns a ServiceTest object Message Alias CATALOG_UPD_SERVICETEST Name jms:queue:CATALOG.UPD.SERVICETEST Type queue Destination TMF API service Producers Body ServiceTestUpdate Headers \"serviceid\" = serviceId, \"propagateToSO\" = true/false Description will update a service test by id and return the service instance. If propagateToSO=true then any service change will be handled by OSOM. This is needed to be controlled in order to avoid update loops Message Alias CATALOG_GET_SERVICETEST_BY_ID Name jms:queue:CATALOG.GET.SERVICETEST Type queue Destination TMF API service Producers OSOM Body String serviceID Description returns a Service TEST instance Message Alias CRD_DEPLOY_CR_REQ Name jms:queue:CRD.DEPLOY.CR_REQ Type queue Destination CRD service Producers OSOM Body CR spec as String Headers related service id Description Returns a String object containing deployment info Message Alias CRD_PATCH_CR_REQ Name jms:queue:CRD.PATCH.CR_REQ Type queue Destination CRD service Producers OSOM Body CR as String Headers related service id Description Returns a String object containing PATCH info Message Alias CRD_DELETE_CR_REQ Name jms:queue:CRD.DELETE.CR_REQ Type queue Destination CRD service Producers OSOM Body CR as String Headers related service id Description Returns a String object containing deletion info"},{"location":"architecture/nfvapi/","title":"API interaction","text":""},{"location":"architecture/nfvapi/#oauth-token","title":"OAuth token","text":"<p>See oauth</p>"},{"location":"architecture/nfvapi/#request-a-protected-api-resource","title":"Request a protected API resource","text":"<p>Example: Get all vxfs (check the <code>Authorization:Bearer</code> to be correct)</p> <pre><code>curl -H \"Authorization:Bearer eybGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX25hbWUiOiJhZG1pbiIsInNjb3BlIjpbIm9wZW5hcGkiLCJhZG1pbiIsInJlYWQiLCJ3cml0ZSJdLCJvcmdhbml6YXRpb24iOiJteW9yZ2FuaXp0aW9uIiwiZXhwIjoxNTcxOTI0MjU2LCJhdXRob3JpdGllcyI6WyJST0xFX01FTlRPUiIsIlJPTEVfQURNSU4iXSwianRpIjoiNzNkZmIxODEtNTMwOS00MmExLThkOWUtOGM3YmQ0YTE1YmU0IiwiY2xpZW50X2lkIjoib3NhcGlXZWJDbGllbnRJZE91dCJ9.Pj_hxnyMGhFhN8avU_DiAw1-LlcaIz5Hp9HNqalw-X4\" http://localhost:13000/osapi/admin/vxfs\n</code></pre> <p>Example response:</p> <pre><code>[\n {\n \"id\": 1,\n \"owner\": {\n \"id\": 1,\n \"organization\": \"ee\",\n \"name\": \"Portal Administrator\",\n \"email\": \"\",\n \"username\": \"admin\",\n \"createdAt\": null\n },\n \"uuid\": \"a954daf2-16da-4b7e-ae42-4825936d453c\",\n \"name\": \"cirros_vnfd\",\n \"iconsrc\": \"/osapi/images/a954daf2-16da-4b7e-ae42-4825936d453c/cirros-64.png\",\n \"shortDescription\": \"cirros_vnfd\",\n \"longDescription\": \"Simple VNF example with a cirros\",\n \"version\": \"1.0\",\n \"packageLocation\": \"/osapi/packages/a954daf2-16da-4b7e-ae42-4825936d453c/cirros_vnf.tar.gz\",\n \"dateCreated\": 1568971426000,\n \"dateUpdated\": 1568981107000,\n \"categories\": [\n {\n \"id\": 3,\n \"name\": \"Service\",\n \"productsCount\": 1,\n \"appscount\": 0,\n \"vxFscount\": 1\n },\n {\n \"id\": 2,\n \"name\": \"Networking\",\n \"productsCount\": 1,\n \"appscount\": 0,\n \"vxFscount\": 1\n }\n ],\n \"extensions\": [],\n \"validationJobs\": [],\n \"screenshots\": \"\",\n \"vendor\": \"OSM\",\n \"published\": false,\n \"termsOfUse\": null,\n \"descriptor\": \"vnfd-catalog:\\n vnfd:\\n - connection-point:\\n - name: eth0\\n type: VPORT\\n description: Simple VNF example with a cirros\\n id: cirros_vnfd\\n logo: cirros-64.png\\n mgmt-interface:\\n cp: eth0\\n name: cirros_vnfd\\n short-name: cirros_vnfd\\n vdu:\\n - count: 1\\n description: cirros_vnfd-VM\\n id: cirros_vnfd-VM\\n image: cirros034\\n interface:\\n - external-connection-point-ref: eth0\\n name: eth0\\n position: '1'\\n type: EXTERNAL\\n virtual-interface:\\n bandwidth: '0'\\n type: VIRTIO\\n vpci: 0000:00:0a.0\\n name: cirros_vnfd-VM\\n vm-flavor:\\n memory-mb: 512\\n storage-gb: 1\\n vcpu-count: 1\\n vendor: OSM\\n version: '1.0'\\n\",\n \"descriptorHTML\": \"<h3>cirros_vnfd</h3><br><b>Vendor: </b>OSM<br><b>Version: </b>1.0<br><b>Description: </b>Simple VNF example with a cirros<br><b>VM Count: </b>1<br><b>vCPU Count: </b>1<br><b>Memory: </b>512 MB<br><b>Storage: </b>1 GB<br>\",\n \"certified\": false,\n \"certifiedBy\": null,\n \"validationStatus\": \"UNDER_REVIEW\",\n \"packagingFormat\": \"OSMvFIVE\",\n \"supportedMANOPlatforms\": [\n {\n \"id\": 1,\n \"name\": \"osm fivee\",\n \"version\": \"osm fivee\",\n \"description\": \"osm five\"\n }\n ],\n \"vxfOnBoardedDescriptors\": [],\n \"vfimagesVDU\": [\n {\n \"id\": 1,\n \"name\": \"cirros034\",\n \"uuid\": \"d4549610-8abd-42ad-97f4-0a64e1c93977\",\n \"shortDescription\": \"Automatically created during vxf cirros_vnfd submission. Owner must update.\",\n \"packageLocation\": null,\n \"publicURL\": null,\n \"dateCreated\": 1568971426000,\n \"dateUpdated\": null,\n \"refVxFs\": [\n {\n \"id\": 1,\n \"name\": \"cirros_vnfd\"\n }\n ],\n \"owner\": {\n \"id\": 1,\n \"organization\": \"ee\",\n \"name\": \"Portal Administrator\",\n \"email\": \"\",\n \"username\": \"admin\",\n \"active\": true,\n \"currentSessionID\": null,\n \"apikey\": \"e41c1cc4-aa56-4b7e-9f4d-64589549d768\",\n \"createdAt\": 1568711859000,\n \"roles\": [\n \"ADMIN\",\n \"MENTOR\"\n ]\n },\n \"published\": false,\n \"termsOfUse\": null,\n \"deployedInfrastructures\": []\n }\n ]\n },\n {\n \"id\": 2,\n \"owner\": {\n \"id\": 1,\n \"organization\": \"ee\",\n \"name\": \"Portal Administrator\",\n \"email\": \"\",\n \"username\": \"admin\",\n \"createdAt\": null\n },\n \"uuid\": \"4ab80095-a63e-4fe7-8598-e1c7e880706e\",\n \"name\": \"cirros_sriov_vnfd\",\n \"iconsrc\": null,\n \"shortDescription\": \"cirros_sriov_vnf\",\n \"longDescription\": \"Simple VNF example with a cirros SRIOV interface\",\n \"version\": \"1.0\",\n \"packageLocation\": \"/osapi/packages/4ab80095-a63e-4fe7-8598-e1c7e880706e/cirros_sriov.tar.gz\",\n \"dateCreated\": 1568971740000,\n \"dateUpdated\": 1568981100000,\n \"categories\": [\n {\n \"id\": 4,\n \"name\": \"tyu\",\n \"productsCount\": 1,\n \"appscount\": 0,\n \"vxFscount\": 1\n },\n {\n \"id\": 5,\n \"name\": \"tyi\",\n \"productsCount\": 1,\n \"appscount\": 0,\n \"vxFscount\": 1\n }\n ],\n \"extensions\": [],\n \"validationJobs\": [],\n \"screenshots\": \"\",\n \"vendor\": \"OSM\",\n \"published\": false,\n \"termsOfUse\": null,\n \"descriptor\": \"vnfd:vnfd-catalog:\\n vnfd:\\n - connection-point:\\n - name: eth0\\n type: VPORT\\n - name: eth1\\n type: VPORT\\n description: Simple VNF example with a cirros SRIOV interface\\n id: cirros_sriov_vnfd\\n logo: cirros-64.png\\n mgmt-interface:\\n cp: eth0\\n name: cirros_sriov_vnf\\n short-name: cirros_sriov_vnf\\n vdu:\\n - count: 1\\n description: cirros_sriov_vnfd-VM\\n guest-epa:\\n cpu-pinning-policy: DEDICATED\\n cpu-thread-pinning-policy: PREFER\\n mempage-size: SMALL\\n numa-node-policy:\\n mem-policy: STRICT\\n node:\\n - id: '1'\\n node-cnt: '1'\\n id: cirros_sriov_vnfd-VM\\n image: cirros-0.3.6-x86_64\\n interface:\\n - external-connection-point-ref: eth0\\n name: eth0\\n position: '1'\\n type: EXTERNAL\\n virtual-interface:\\n bandwidth: '0'\\n type: VIRTIO\\n vpci: 0000:00:0a.0\\n - external-connection-point-ref: eth1\\n name: eth1\\n position: '2'\\n type: EXTERNAL\\n virtual-interface:\\n type: SR-IOV\\n name: cirros_sriov_vnfd-VM\\n vm-flavor:\\n memory-mb: 4096\\n storage-gb: 10\\n vcpu-count: 4\\n vendor: OSM\\n version: '1.0'\\n\",\n \"descriptorHTML\": \"<h3>cirros_sriov_vnf</h3><br><b>Vendor: </b>OSM<br><b>Version: </b>1.0<br><b>Description: </b>Simple VNF example with a cirros SRIOV interface<br><b>VM Count: </b>1<br><b>vCPU Count: </b>1<br><b>Memory: </b>4096 MB<br><b>Storage: </b>10 GB<br>\",\n \"certified\": false,\n \"certifiedBy\": null,\n \"validationStatus\": \"UNDER_REVIEW\",\n \"packagingFormat\": \"OSMvFIVE\",\n \"supportedMANOPlatforms\": [\n {\n \"id\": 1,\n \"name\": \"osm fivee\",\n \"version\": \"osm fivee\",\n \"description\": \"osm five\"\n }\n ],\n \"vxfOnBoardedDescriptors\": [],\n \"vfimagesVDU\": [\n {\n \"id\": 2,\n \"name\": \"cirros-0.3.6-x86_64\",\n \"uuid\": \"be121176-1d62-4a1b-a3c1-7dce2e069d22\",\n \"shortDescription\": \"Automatically created during vxf cirros_sriov_vnfd submission. Owner must update.\",\n \"packageLocation\": null,\n \"publicURL\": null,\n \"dateCreated\": 1568971740000,\n \"dateUpdated\": null,\n \"refVxFs\": [\n {\n \"id\": 2,\n \"name\": \"cirros_sriov_vnfd\"\n }\n ],\n \"owner\": {\n \"id\": 1,\n \"organization\": \"ee\",\n \"name\": \"Portal Administrator\",\n \"email\": \"\",\n \"username\": \"admin\",\n \"active\": true,\n \"currentSessionID\": null,\n \"apikey\": \"e41c1cc4-aa56-4b7e-9f4d-64589549d768\",\n \"createdAt\": 1568711859000,\n \"roles\": [\n \"ROLE_ADMIN\",\n \"ROLE_MENTOR\"\n ]\n },\n \"published\": false,\n \"termsOfUse\": null,\n \"deployedInfrastructures\": []\n }\n ]\n }\n]\n</code></pre>"},{"location":"architecture/oauth/","title":"Authentication Server","text":"<p>Authentication is based on oAuth2. Our authentication service is a Keycloak server which is deployed with Openslice deployment </p> <p>API users needs to authenticate. All APIs (except grant token request) must include Bearer token in request Authorization header.</p>"},{"location":"architecture/oauth/#oauth-token","title":"OAuth token","text":"<p>Get first an oauth token, using your username and password. </p> <pre><code>curl -X POST http://portal.openslice.io/auth/realms/openslice/protocol/openid-connect/token -H 'Content-Type: application/x-www-form-urlencoded' -d 'username=demouser' -d 'password=demouser' -d 'grant_type=password' -d 'client_id=osapiWebClientId' \n</code></pre> <p>response:</p> <pre><code> {\"access_token\":\"eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJHZFRjQnpxczg2VW10NTRVZV8ybTJyWHJkV3dzaWdSZE9EUldMYm1memNvIn0.eyJleHAiOjE1ODgyNDA1NzAsImlhdCI6MTU4ODI0MDI3MCwianRpIjoiOGI2ZTU0NWUtNDIyYy00NzFiLWEwN2UtYTUzYzY1NDQ0MzZmIiwiaXNzIjoiaHR0cDovL3BvcnRhbC5vcGVuc2xpY2UuaW8vYXV0aC9yZWFsbXMvb3BlbnNsaWNlIiwiYXVkIjoiYWNjb3VudCIsInN1YiI6ImExYTI3NjVhLWVjODMtNDQ1Ni1iN2IyLTIwNzMxOTg2ZTAzNSIsInR5cCI6IkJlYXJlciIsImF6cCI6Im9zYXBpV2ViQ2xpZW50SWQiLCJzZXNzaW9uX3N0YXRlIjoiMzM1MGY0OTMtNjYyNy00MzczLTg1NDQtZGVmZDI3YWQzYzc0IiwiYWNyIjoiMSIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjEzMDgyIiwiaHR0cDovL2xvY2FsaG9zdCIsImh0dHA6Ly9vcGVuc2xpY2UuaW8iLCJodHRwOi8vbG9jYWxob3N0OjEzMDAwIiwiaHR0cDovL2xvY2FsaG9zdDo0MjAwIiwiaHR0cDovL3BvcnRhbC5vcGVuc2xpY2UuaW8iXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIk5GVl9ERVZFTE9QRVIiLCJvZmZsaW5lX2FjY2VzcyIsInVtYV9hdXRob3JpemF0aW9uIiwiRVhQRVJJTUVOVEVSIiwiVVNFUiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoicHJvZmlsZSBlbWFpbCIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJkZW1vdXNlciJ9.TnzzpRLMD94UTKpT5_wkr1h4_3KUQmr4TGvFLpJ7cZx-Klrv8tB_eRkWnPqqzCAM9G21a1qXboL8MLMW8ECzG7HYKpobKOGr7LSczMOTdA2ZDyBCRUSOdW77pchu54tJ0ITEkFaDwSKMKKt04V_Sy4U-eIndj0XzzRlkDolWDnK4Z2lRaXAI6fMwOKx1Toa6RfOcemxtzl3pdtjPx92zo6MaKlbIqHK82lxdK0k8aQQaT6TmIrXbZKV2dU_1d3O0q0dVUEZJ_1kzwqOFkmxr9w0EnndC6ccYJlDAr_-GgUhhhNOn5v6tjYLUQdj5e4KEAsxIPzaCreK4un7mEAPmDw\",\"expires_in\":300,\"refresh_expires_in\":1800,\"refresh_token\":\"eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICIwZjUxMDk5Yy0wNTIzLTRjNGQtODM0Zi1iNDc0YzBjOTA1MzkifQ.eyJleHAiOjE1ODgyNDIwNzAsImlhdCI6MTU4ODI0MDI3MCwianRpIjoiZmViOTg5NWEtOTY5ZS00MzIzLWJjY2QtZTY2YzQ0NGE1MzJlIiwiaXNzIjoiaHR0cDovL3BvcnRhbC5vcGVuc2xpY2UuaW8vYXV0aC9yZWFsbXMvb3BlbnNsaWNlIiwiYXVkIjoiaHR0cDovL3BvcnRhbC5vcGVuc2xpY2UuaW8vYXV0aC9yZWFsbXMvb3BlbnNsaWNlIiwic3ViIjoiYTFhMjc2NWEtZWM4My00NDU2LWI3YjItMjA3MzE5ODZlMDM1IiwidHlwIjoiUmVmcmVzaCIsImF6cCI6Im9zYXBpV2ViQ2xpZW50SWQiLCJzZXNzaW9uX3N0YXRlIjoiMzM1MGY0OTMtNjYyNy00MzczLTg1NDQtZGVmZDI3YWQzYzc0Iiwic2NvcGUiOiJwcm9maWxlIGVtYWlsIn0.cDTx9BE1Df8EfGYm3VLr_MNFeymxZtJhMtlK7PVbIuk\",\"token_type\":\"bearer\",\"not-before-policy\":1586797346,\"session_state\":\"3350f493-6627-4373-8544-defd27ad3c74\",\"scope\":\"profile email\"}\n\n</code></pre> <p>The <code>access_token</code> will be used next as a Bearer.</p> <pre><code>curl http://portal.openslice.io/tmf-api/serviceCatalogManagement/v4/serviceCatalog -H 'Authorization: Bearer yJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJHZFRjQnpxczg2VW10NTRVZV8ybTJyWHJkV3dzaWdSZE9EUldMYm1memNvIn0.eyJleHAiOjE1ODgyNDA1MjQsImlhdCI6MTU4ODI0MDIyNCwianRpIjoiYjg0NGYxZDAtMzk3Mi00YTMyLThiMWEtZDAxMDY3OGZjMTQ4IiwiaXNzIjoiaHR0cDovL3BvcnRhbC5vcGVuc2xpY2UuaW8vYXV0aC9yZWFsbXMvb3BlbnNsaWNlIiwic3ViIjoiYTFhMjc2NWEtZWM4My00NDU2LWI3YjItMjA3MzE5ODZlMDM1IiwidHlwIjoiQmVhcmVyIiwiYXpwIjoiYWRtaW4tY2xpIiwic2Vzc2lvbl9zdGF0ZSI6ImFmMmMzZmY1LTE4YWQtNDFkNC1hYTAyLTFlMGJkNzNmOTM5MSIsImFjciI6IjEiLCJzY29wZSI6InByb2ZpbGUgZW1haWwiLCJlbWFpbF92ZXJpZmllZCI6dHJ1ZSwicHJlZmVycmVkX3VzZXJuYW1lIjoiZGVtb3VzZXIifQ.SMtgV1E44_K_MQumGXZtWsLGVhYNaoM8Pk-DiFIZtUP4Zu-ervOsxHVQMX1frgVERR4jJidBcSshy9TnJ3UjF4l33WujHltbs-1UPy-gaIufVuEpl8RmbjOti3Up70vLfLXbzb6kN6WaahgobWXlbJsSXXwaBPQP6vSX5KigCa8TmzXcuqom14lOrlU-RB2zQTlJ30p7d9ag-a7o3I5m9GZWLJCZW2UYMl1JkskTHKgilA8HFQY4C9DYwWu8YDMyzqQSNumrTlURalBFidFbZvb1kp4dAyct8TysSWSbxxiwaL2RX1PWUqk-5Fpc1Q6BnBC8muMheiukFuoSkuADAg'^C\nubuntu@portal:~$ curl http://portal.openslice.io/tmf-api/serviceCatalogManagement/v4/serviceCatalog -H 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJHZFRjQnpxczg2VW10NTRVZV8ybTJyWHJkV3dzaWdSZE9EUldMYm1memNvIn0.eyJleHAiOjE1ODgyNDA1NzAsImlhdCI6MTU4ODI0MDI3MCwianRpIjoiOGI2ZTU0NWUtNDIyYy00NzFiLWEwN2UtYTUzYzY1NDQ0MzZmIiwiaXNzIjoiaHR0cDovL3BvcnRhbC5vcGVuc2xpY2UuaW8vYXV0aC9yZWFsbXMvb3BlbnNsaWNlIiwiYXVkIjoiYWNjb3VudCIsInN1YiI6ImExYTI3NjVhLWVjODMtNDQ1Ni1iN2IyLTIwNzMxOTg2ZTAzNSIsInR5cCI6IkJlYXJlciIsImF6cCI6Im9zYXBpV2ViQ2xpZW50SWQiLCJzZXNzaW9uX3N0YXRlIjoiMzM1MGY0OTMtNjYyNy00MzczLTg1NDQtZGVmZDI3YWQzYzc0IiwiYWNyIjoiMSIsImFsbG93ZWQtb3JpZ2lucyI6WyJodHRwOi8vbG9jYWxob3N0OjEzMDgyIiwiaHR0cDovL2xvY2FsaG9zdCIsImh0dHA6Ly9vcGVuc2xpY2UuaW8iLCJodHRwOi8vbG9jYWxob3N0OjEzMDAwIiwiaHR0cDovL2xvY2FsaG9zdDo0MjAwIiwiaHR0cDovL3BvcnRhbC5vcGVuc2xpY2UuaW8iXSwicmVhbG1fYWNjZXNzIjp7InJvbGVzIjpbIk5GVl9ERVZFTE9QRVIiLCJvZmZsaW5lX2FjY2VzcyIsInVtYV9hdXRob3JpemF0aW9uIiwiRVhQRVJJTUVOVEVSIiwiVVNFUiJdfSwicmVzb3VyY2VfYWNjZXNzIjp7ImFjY291bnQiOnsicm9sZXMiOlsibWFuYWdlLWFjY291bnQiLCJtYW5hZ2UtYWNjb3VudC1saW5rcyIsInZpZXctcHJvZmlsZSJdfX0sInNjb3BlIjoicHJvZmlsZSBlbWFpbCIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJkZW1vdXNlciJ9.TnzzpRLMD94UTKpT5_wkr1h4_3KUQmr4TGvFLpJ7cZx-Klrv8tB_eRkWnPqqzCAM9G21a1qXboL8MLMW8ECzG7HYKpobKOGr7LSczMOTdA2ZDyBCRUSOdW77pchu54tJ0ITEkFaDwSKMKKt04V_Sy4U-eIndj0XzzRlkDolWDnK4Z2lRaXAI6fMwOKx1Toa6RfOcemxtzl3pdtjPx92zo6MaKlbIqHK82lxdK0k8aQQaT6TmIrXbZKV2dU_1d3O0q0dVUEZJ_1kzwqOFkmxr9w0EnndC6ccYJlDAr_-GgUhhhNOn5v6tjYLUQdj5e4KEAsxIPzaCreK4un7mEAPmDw'\n\nResponse:\n\n\n[{\"uuid\":\"9e186cd5-b2b2-4a06-b1d6-895720193bc9\",\"lastUpdate\":\"2020-03-11T23:19:05Z\",\"@baseType\":\"BaseEntity\",\"@schemaLocation\":null,\"@type\":\"ServiceCatalog\",\"href\":null,\"name\":\"Example Facility Services\",\"description\":\"Example Facility Services\",\"lifecycleStatus\":\"Active\",\"version\":\"1.0\",\"validFor\":{\"endDateTime\":\"2039-11-20T23:07:21Z\",\"startDateTime\":\"2019-11-20T23:07:21Z\"},\"relatedParty\":null,\"id\":\"9e186cd5-b2b2-4a06-b1d6-895720193bc9\",\"category\":[{\"@baseType\":\"org.etsi.osl.tmf.scm633.model.ServiceCategoryRef\",\"@schemaLocation\":null,\"@type\":\"org.etsi.osl.tmf.scm633.model.ServiceCategoryRef\",\"href\":null,\"name\":\"Generic Services\",\"@referredType\":null,\"id\":\"98b9adf1-a1d6-4165-855f-153ddc2131b1\"},{\"@baseType\":\"org.etsi.osl.tmf.scm633.model.ServiceCategoryRef\",\"@schemaLocation\":null,\"@type\":\"org.etsi.osl.tmf.scm633.model.ServiceCategoryRef\",\"href\":null,\"name\":\"External\",\"@referredType\":null,\"id\":\"08ffdb3c-6237-45d0-9f3a-d43b5fc5f0b6\"},{\"@baseType\":\"org.etsi.osl.tmf.scm633.model.ServiceCategoryRef\",\"@schemaLocation\":null,\"@type\":\"org.etsi.osl.tmf.scm633.model.ServiceCategoryRef\",\"href\":null,\"name\":\"eMBB\",\"@referredType\":null,\"id\":\"ef2c90dd-b65e-4a9f-a9c3-427c9fb0219b\"}]}]\n\n\n</code></pre>"},{"location":"architecture/osom/","title":"Openslice Service Orchestration and Order Management - OSOM","text":"<p>OSOM is a service responsible for:</p> <ul> <li>Service Order Management (SOM)</li> <li>Service Orchestration (SO)</li> </ul> <p>It uses open source Flowable Business process engine (https://www.flowable.org) .</p> <p>A Service Order follows the states as defined in TMF641 specification: </p> <p></p>"},{"location":"architecture/osom/#initial-state","title":"Initial state","text":"<p>When a new order is created, it goes into the Initial state. It is stored in the repository and triggers an Event.</p> <p></p> <p>Administrators are notified usually from the Ticketing System of a new order. They login to Openslice and change the State of the order either to ACKNOWLEDGED or REJECTED. If ACKNOWLEDGED they can Propose a startDate, add Notes, and add any additional service items</p>"},{"location":"architecture/osom/#order-scheduler","title":"Order scheduler","text":"<p>A process checks every 1 minute for ACKNOWLEDGED orders.</p> <p></p> <p></p> <p>It retrieves all orders that are in ACKNOWLEDGED state and if the start date is in time it will initialize the process by settingn the order in IN_PROGRESS state. Finally the Start Order Process will start.</p>"},{"location":"architecture/osom/#start-order-process","title":"Start order process","text":"<p>This process for now is a draft simple prototype to make a simple orchestration via NFVO. Here the actual Services (TMF638/640 model) are created and attached to Service Order and Service Inventory.</p> <p></p> <p></p> <p>We expect here to check which tasks can be orchestrated by NFVO and which by human. We create the equivalent Services(TMF638/640 model) for this order.</p> <ol> <li>During check it should decide to create Service(s) for this service order O1 and send it to ServiceInventory</li> <li>The Services(TMF638 model) are assigned to the Order O1 In supportService List</li> <li>Each OrderItem OI1 is related to one serviceSpecification</li> <li>Each ServiceSpecification has also related serviceSpecRelationships</li> <li>So if we receive an order O1 for a ServiceSpec A which relates to (a bundle of) 3 specs(2 CFS, 1 RFS) we do the following:<ol> <li>Create a Service S_A(TMF638 model) for ServiceSpec A for Order O1</li> <li>We create also 3 Services S_C1, S_C2 and S_R1 equivalent to the serviceSpecRelationships (2 CFS, 1 RFS) </li> <li>At this point the order will have 1 Local Service Orchestration Process(S_A), 2 supportingServices refs(S_C1, S_C2) and 1 supportingResource(S_R1)</li> <li>The 3 supportingServices and 1 supportingResource correspond to total 4 Services in ServiceInventory</li> <li>Service S_A will have: <ol> <li>startMode 1: Automatically by the managed environment</li> <li>State: RESERVED and the Lifecycle will be handled by OSOM</li> </ol> </li> <li>Services S_C1 and S_C2 we decide that cannot be orchestrated then they have <ol> <li>startMode: 3: Manually by the Provider of the Service</li> <li>State: RESERVED and the Lifecycle will be handled by OSOM</li> <li>If the CFS is a bundle spec it is further recursively orchestrated </li> </ol> </li> <li>Service S_R1 will have <ol> <li>startMode 1: Automatically by the managed environment.</li> <li>State: RESERVED</li> <li>IF The Service has the characteristic CharacteristicByName( \"NSDID\") it will be further processed by the NFVO </li> </ol> </li> </ol> </li> </ol> <p>There will be two instances of task \"User Task Manual Complete Service\" each for Services S_C1 and S_C2. The task is Transient for now. It displays only the services that are not automated! Here is a flow for future:</p> <ol> <li>We wait here for human decision.</li> <li>From API we get a result: a. If set to ACTIVE/TERMINATED then we complete the task b. In any other state we stay in this task until it is resolved as in step a c. The Status of ORDER O1 is also updated to PARTIAL</li> </ol> <p>There will be an instance of NFVODeploymentRequest process each for Service S_R1. (see later)</p> <ol> <li>This process is related with the NFVO orchestration</li> <li>It will send a msg to NFVO(s?) for a specific deployment request</li> </ol> <p>All services in \"Order Complete\" are in a status:</p> <ol> <li>Depending on the result the service S_A is either ACTIVE or INACTIVE or TERMINATED</li> <li>The Status of ORDER O1 is also updated to COMPLETED or PARTIAL (in case we have some services running) or FAILED (in cases we have errors)</li> </ol> <p>A Service follows the states as defined in TMF638 Service Inventory specification: </p> <p></p>"},{"location":"architecture/osom/#nfvodeploymentrequest-process","title":"NFVODeploymentRequest process","text":"<p>This process is related with the NFVO orchestration It will send a msg to NFVO(s?) for a specific deployment request Then it checks the deployment status. It will wait 30 secs each time until the deployment is running (or failed)</p>"},{"location":"architecture/osom/#check-in-progress-orders-process","title":"Check In Progress orders process","text":"<p>Every 1 minute the \"Check In Progress Orders\" process is executed checking if a supported Service changed state (i.e. to ACTIVE) then the whole Order will change state (e.g. go to COMPLETED)</p> <p></p>"},{"location":"architecture/osom/#external-service-provider-deployment-request-process","title":"External Service Provider Deployment Request process","text":"<p>This process contains tasks for submitting order requests to external partners. - Submit Order To External Service Provider Task: This task creates automatically a Service Order request to a 3rd party provider SO that hosts the Service Specification - Check external service order fulfillment task: This task Check external partner for Service creations and updates our local inventory of services the service characteristics of remote Service Inventory</p>"},{"location":"architecture/osom/#fetch-partner-services-process","title":"Fetch Partner Services Process","text":"<p>Every 2 minutes the \"fetchPartnerServicesProcess\" process is executed checking remote Partner Organizations for changes in the published catalogues. The Fetch and Update External Partner Services Task is executed in paralle l for each Partner Organization </p>"},{"location":"architecture/osom/#local-service-orchestration-process","title":"Local Service Orchestration Process","text":"<p>This process handles automatically services that need to be further orchestrated or processed by OSOM. For example, for a CFS Bundled service we create such automated service instances that just aggregate the underlying services. </p>"},{"location":"architecture/tmfapi/","title":"TMF OpenAPI specification","text":"<p>PLease check the complete specification here.</p>"},{"location":"architecture/tmfapi/#api-interaction","title":"API interaction","text":""},{"location":"architecture/tmfapi/#oauth-token","title":"OAuth token","text":"<p>See oauth</p>"},{"location":"architecture/tmfapi/#request-a-protected-api-resource","title":"Request a protected API resource","text":"<p>Example: Get all Service Catalogs (check the <code>Authorization:Bearer</code> to be correct)</p> <pre><code>curl -H \"Authorization:Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VyX25hbWUiOiJhZG1pbiIsInNjb3BlIjpbIm9wZW5hcGkiLCJhZG1pbiIsInJlYWQiLCJ3cml0ZSJdLCJvcmdhbml6YXRpb24iOiJteW9yZ2FuaXp0aW9uIiwiZXhwIjoxNTc4NTA1MDcyLCJhdXRob3JpdGllcyI6WyJST0xFX01FTlRPUiIsIlJPTEVfQURNSU4iXSwianRpIjoiMTFlNGYxYTUtZDY0Ny00YzA1LWE0ZGMtYWFhYzUyMjk4YzMwIiwiY2xpZW50X2lkIjoib3NhcGlXZWJDbGllbnRJZE91dCJ9.gm7cKdusDrdMRkxEiFU5sENKGRC1xwVj2SgPRmE9xxx\" -H \"accept: application/json;charset=utf-8\" -X GET \"http://portal.openslice.io/tmf-api/serviceCatalogManagement/v4/serviceCatalog\"\n\n</code></pre> <p>response:</p> <pre><code>[\n {\n \"uuid\": \"9e186cd5-b2b2-4a06-b1d6-895720193bc9\",\n \"lastUpdate\": \"2019-12-19T10:45:55Z\",\n \"@baseType\": \"BaseEntity\",\n \"@schemaLocation\": null,\n \"@type\": \"ServiceCatalog\",\n \"href\": null,\n \"name\": \"Example Facility Services\",\n \"description\": \"Example Facility Services\",\n \"lifecycleStatus\": \"Active\",\n \"version\": \"1.0\",\n \"validFor\": {\n \"endDateTime\": \"2039-11-20T23:07:21Z\",\n \"startDateTime\": \"2019-11-20T23:07:21Z\"\n },\n \"relatedParty\": null,\n \"id\": \"9e186cd5-b2b2-4a06-b1d6-895720193bc9\",\n \"category\": [\n {\n \"@baseType\": \"org.etsi.osl.tmf.scm633.model.ServiceCategoryRef\",\n \"@schemaLocation\": null,\n \"@type\": \"org.etsi.osl.tmf.scm633.model.ServiceCategoryRef\",\n \"href\": null,\n \"name\": \"eMBB\",\n \"@referredType\": null,\n \"id\": \"ef2c90dd-b65e-4a9f-a9c3-427c9fb0219b\"\n },\n {\n \"@baseType\": \"org.etsi.osl.tmf.scm633.model.ServiceCategoryRef\",\n \"@schemaLocation\": null,\n \"@type\": \"org.etsi.osl.tmf.scm633.model.ServiceCategoryRef\",\n \"href\": null,\n \"name\": \"Generic Services\",\n \"@referredType\": null,\n \"id\": \"98b9adf1-a1d6-4165-855f-153ddc2131b1\"\n }\n ]\n }\n]\n</code></pre>"},{"location":"architecture/CRIDGE/CRIDGEforDevelopers/","title":"CRIDGE: A Service to manage Custom Resources in a Kubernetes Cluster","text":""},{"location":"architecture/CRIDGE/CRIDGEforDevelopers/#intended-audience-osl-developers","title":"Intended Audience: OSL developers","text":"<p>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.</p> <p>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.</p> <p>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.</p> <ol> <li> <p>CRIDGE service allows OSL to:</p> <ul> <li>Create and manage Custom Resources (CRs) using installed CRDs on a target Kubernetes cluster.</li> <li>Facilitate complex orchestration scenarios by wrapping Kubernetes APIs as TMF APIs and models.</li> <li>Handles connectivity to a Kubernetes cluster and manages the lifecycle of CRDs</li> <li>Wraps the Kubernetes API, Receives and provides resources towards other OSL services via the service bus</li> </ul> </li> <li> <p>Enabling Loose Coupling and Orchestration</p> <ul> <li>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.</li> <li>Familiar Deployment: Developers can create and deploy applications using familiar tools such as Helm charts, simplifying the process and reducing the learning curve.</li> </ul> </li> <li> <p>Ecosystem Reusability</p> <ul> <li>CRIDGE capitalizes on the extensive Kubernetes ecosystem, particularly focusing on operators (CRDs).</li> <li>Key repositories and hubs such as artifacthub.io and Operatorhub.io can be utilized for finding and deploying operators.</li> </ul> </li> <li> <p>Service Catalog Exposure and Deployment</p> <p>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.</p> </li> </ol> <p>Why the CRIDGE name? we wanted to build a service that maps TMF models to CRDs; a kind of a CRD to TMF bridge. Therefore CRIDGE was born</p>"},{"location":"architecture/CRIDGE/CRIDGEforDevelopers/#approach","title":"Approach","text":"<p>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.</p> <p>The following image illustrates the approach.</p> <p></p> <ol> <li>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</li> <li>Service Orders can be created for this service specification. The OSL Orchestrator (OSOM) will manage the lifecycle of the Service Order.</li> <li>OSOM creates a Resource in OSL Resource inventory and requests (via CRIDGE) a new Custom Resource (CR) in the target cluster<ul> <li>The resource is created in a specific namespace (for example the UUID of the Service Order)</li> <li>A CR in a cluster will be mapped in TMF model as a Resource in the resource Inventory</li> <li>Other related resources created by the CRD Controller within the namespace are automatically created in OSL Resource Inventory under the same Service Order</li> </ul> </li> </ol> <p></p> <p>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:</p> <ul> <li>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).</li> <li>Service Bus: This is the communication layer that facilitates interaction between the CRIDGE service and other OSL services.</li> <li>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.</li> <li> <p>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.</p> <p>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 :</p> </li> </ul> <pre><code> apiVersion: apiextensions.k8s.io/v1\n kind: CustomResourceDefinition\n metadata:\n name: myresource.example.com\n</code></pre> <ul> <li>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.</li> </ul> <p>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:</p> <pre><code> apiVersion: example.com/v1\n kind: Myresource\n metadata:\n name: example_resource_1\n</code></pre> <p>In a nutchell:</p> <ul> <li>Various OSL services use the Service Bus to communicate with CRIDGE.</li> <li>CRIDGE converts requests towards Kubernetes API and vice-versa, facilitating the integration of custom resources with other OSL services.</li> <li>CRDs are defined and managed through the K8s API. The example CRD is named myresource.example.com.</li> <li>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.<pre><code>> The example CRD myresource.example.com allows the creation of custom resources of type Myresource.\n> Instances of Myresource are created in various namespaces, each with unique names like example_resource_1.\n</code></pre> </li> </ul>"},{"location":"architecture/CRIDGE/CRIDGEforDevelopers/#handling-more-than-one-clusters","title":"Handling more than one clusters","text":"<p>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:</p> <p></p> <p>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</p> <p>A CRD has a globally unique name for example mycrd.example.com. So we need to somehow identify also the different cluster</p>"},{"location":"architecture/CRIDGE/CRIDGEforDevelopers/#awareness-for-crds-and-crs-in-cluster","title":"Awareness for CRDs and CRs in cluster","text":"<p>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.</p> <p>The sync process is found in the code and explained by the following picture:</p> <p></p> <p>WatcherService is executed when the cridge service application starts (see onApplicationEvent). First things:</p> <ul> <li>KubernetesClientResource is a class that wraps fabric8\u2019s KubernetesClient<ul> <li>This fabric8 KubernetesClient is initialized from the kubeconf and default context of the machine that runs CRIDGE</li> </ul> </li> <li>On CRIDGE Start up we try to register this cluster and context to OSL catalogs.<ul> <li>See registerKubernetesClientInOSLResource method which registers the KubernetesContextDefinition in Resource Inventory as a LogicalResource via createOrUpdateResourceByNameCategoryVersion method</li> </ul> </li> <li>After the creation(or update) of this cluster as a Resource in OSL we proceed to create SharedIndexInformers for CustomResourceDefinition objects</li> <li>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)</li> <li>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)<ul> <li>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</li> </ul> </li> <li>On ADD event:<ul> <li>The CRD is transformed to OSL Kubernetes domain model: method kubernetesClientResource.KubernetesCRD2OpensliceCRD</li> <li>Then the OSL Kubernetes domain model is:<ul> <li>transformed to Resource Specification and is stored to catalog (see createOrUpdateResourceSpecByNameCategoryVersion)</li> <li>Transformed to Resource and is stored to catalog (see createOrUpdateResourceByNameCategoryVersion)</li> </ul> </li> <li>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</li> <li>Then for this CRD a Watcher is added for all Resources of this Kind (fabric8\u2019s GenericKubernetesResource entity) </li> <li>When we have a newly added/updated/deleted resource of a certain CRD the method updateGenericKubernetesResourceInOSLCatalog is called for this object (fabric8\u2019s GenericKubernetesResource entity)</li> <li>We examine if the resource has label org.etsi.osl.resourceId<ul> <li>This label is added by OSOM during service orders to correlate K8S requested resources with resources in inventory</li> </ul> </li> <li>If the label exists, we update the resource by ID updateResourceById</li> <li>Else a resource is created in catalog</li> </ul> </li> </ul>"},{"location":"architecture/CRIDGE/CRIDGEforDevelopers/#deployment-of-a-new-cr-based-on-a-crd","title":"Deployment of a new CR based on a CRD","text":"<ul> <li>A message arrives to deploy a CR<ul> <li>The call examines if this CRIDGE service can handle the request (based on context and masterURL)</li> </ul> </li> <li>There are headers received and a crspec in json</li> <li>The crspec is unmarshaled as GenericKubernetesResource</li> <li>Headers are in format org.etsi.osl.*</li> <li>These headers are injected as labels <ul> <li>(see later in orchestration)</li> </ul> </li> <li>A namespace is created for this resource</li> <li>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)</li> </ul>"},{"location":"architecture/CRIDGE/CRIDGEforDevelopers/#expose-crds-as-service-specifications-in-openslice-catalogs","title":"Expose CRDs as Service Specifications in OpenSlice catalogs","text":"<p>See ExposingKubernetesResources</p>"},{"location":"architecture/CRIDGE/CRIDGEforDevelopers/#service-orchestration-and-crdscrs","title":"Service Orchestration and CRDs/CRs","text":"<p>OSOM checks the presence of attribute _CR_SPEC at the RFS to make a request for a CR deployment</p> <ul> <li>_CR_SPEC is a JSON or YAML string that is used for the request<ul> <li>It is similar to what one will do with e.g. a kubectl apply</li> <li>There are tools to translate a yaml file to a json</li> </ul> </li> </ul> <p>LCM rules can be used to change attributes of this yaml/json file, before sending this for orchestration</p> <p>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</p> <p>OSOM sends to CRIDGE a message with the following information:</p> <ul> <li>currentContextCluster: current context of cluster </li> <li>clusterMasterURL: current master url of the cluster </li> <li>org.etsi.osl.serviceId: This is the related service id that the created resource has a reference </li> <li>org.etsi.osl.resourceId: This is the related resource id that the created CR will wrap and reference. </li> <li>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 </li> <li>org.etsi.osl.serviceOrderId: the related service order id of this deployment request </li> <li>org.etsi.osl.namespace: requested namespace name </li> <li>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) </li> <li>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) </li> <li>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) </li> <li>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) </li> <li>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) </li> <li>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) </li> <li> <p>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) </p> </li> <li> <p>Parameters:</p> <ul> <li>aService reference to the service that the resource and the CR belongs to</li> <li>resourceCR reference the equivalent resource in TMF repo of the target CR. One to one mapping</li> <li>orderId related service order ID</li> <li>startDate start date of the deployment (not used currently)</li> <li>endDate end date of the deployment (not used currently)</li> <li>_CR_SPEC the spec that is sent to cridge (in json)</li> </ul> </li> <li> <p>Returns:</p> <ul> <li>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</li> </ul> </li> <li> <p>CRIDGE receives the message and creates according to the labels the necessary CR</p> </li> <li>It monitors the created resource(s) in namespace (see the Sequence Diagram in previous images)</li> <li>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</li> <li>It sends to the message bus the current resource for creation or update to the TMF service inventory</li> </ul>"},{"location":"architecture/CRIDGE/CRIDGEforDevelopers/#probe-further","title":"Probe further","text":"<ul> <li>See examples of exposing operators via OpenSlice:<ul> <li>Exposing Kubernetes Operators as a Service : Offering \"Calculator as a Service\" through OpenSlice</li> </ul> </li> </ul>"},{"location":"contributing/developing/","title":"Developing","text":"<p>OpenSlice backend services are mainly implemented with Java 17 or above and Spring boot.</p> <p>OpenSlice uses various subsystems and depending on the module would you like to work, other subsystems must be present (you can disable them though in the code, e.g. at docker-compose.yaml file).</p> <p>To get the latest development branch:</p> <pre><code>wget https://labs.etsi.org/rep/osl/code/org.etsi.osl.main/-/raw/develop/compose/deploy.sh \nsudo ./deploy.sh develop #[or replace develop with other branch name]\n</code></pre> <p>You may follow the installation process, as described at \"develop\" tagged documentation.</p> <p>To work on a specific subsystem e.g. org.etsi.osl.tmf.api, you must:</p> <p>1a - Deploy only the core necessary subsystems through:</p> <pre><code>sudo docker compose --profile dev down;sudo docker compose --profile dev up -d --build\n</code></pre> <p>Note --profile dev that will only deploy the core dependency subsystems, instead of the whole OpenSlice.</p> <p>1b - Or alternatively, commend out the respective container from the docker-compose.yaml file, so as to deploy the whole OpenSlice, except the subsystem you want to work on, following the provided installation steps.</p> <p>2 - Clone the respective repository, e.g. https://labs.etsi.org/rep/osl/code/org.etsi.osl.tmf.api/-/tree/develop</p> <p>3 - Code :)</p>"},{"location":"contributing/developing/#general-requirements","title":"General requirements","text":"<ul> <li>Docker should be installed in your development environment</li> <li>Run the core subsystems (see above section)</li> </ul>"},{"location":"contributing/developing/#slack","title":"Slack","text":"<p>Feel free to join OpenSlice Slack for any development oriented questions.</p>"},{"location":"contributing/developing/#examples-of-developing-on-specific-subsystems","title":"Examples of developing on specific subsystems","text":""},{"location":"contributing/developing/#vnfnsd-catalog-management-and-nsd-deployment-api-service","title":"VNF/NSD Catalog Management and NSD Deployment API service","text":"<p>Clone the repository: https://labs.etsi.org/rep/osl/code/org.etsi.osl.portal.api/-/tree/develop</p> <p>Check the docker-compose.yml file. Default port is 13080. Check specifically the datasource username/password, server port.</p> <p>Make sure that the core subsystems are up and running.</p> <p>Execute it with </p> <pre><code>mvn spring-boot:run\n</code></pre> <p>For verification, Swagger API of the service is at <code>http://localhost:13000/osapi/swagger-ui/index.html</code>. </p> <p>There, you may try there various REST actions and authenticate via the OAuth server without the use of the UI.</p>"},{"location":"contributing/developing/#vnfnsd-catalog-management-and-nsd-deployment-web-ui-service","title":"VNF/NSD Catalog Management and NSD Deployment WEB UI service","text":"<p>The Web UI is written in AngularJS.</p> <p>Clone the repository: https://labs.etsi.org/rep/osl/code/org.etsi.osl.portal.web/-/tree/develop</p> <p>By default the project org.etsi.osl.portal.api exposes the folder ../org.etsi.osl.portal.web/src/ in a folder testweb (Check class MvcConfig.java in org.etsi.osl.portal.api) for development. (In production nginx is used). Point your browser to <code>http://localhost:13000/osapi/testweb/index.html/</code></p>"},{"location":"contributing/developing/#versionrelease-management","title":"Version/release management","text":"<p>Check this nice article on how we develop and release versions.</p> <p>https://nvie.com/posts/a-successful-git-branching-model/</p> <p>We develop in the develop branch and follow a issue driven development model.</p>"},{"location":"contributing/developing/#wishlist","title":"Wishlist","text":"<p>Check also our wishlist of new features. You can add your own.</p> <p>See Wishlist.</p>"},{"location":"contributing/wishlist/","title":"TMF API","text":"<ul> <li>RBAC of API endpoints</li> <li>TMF Ticketing API support</li> <li>TMF Product</li> <li>HATEOAS integration</li> <li>Select Specs that can be exposed to partners (maybe with a characteristic?)</li> </ul>"},{"location":"contributing/wishlist/#resource-management","title":"resource management","text":"<ul> <li>Resource Activation and Configuration API TMF702 (NEW) (https://projects.tmforum.org/wiki/pages/viewpage.action?pageId=128855518)</li> </ul>"},{"location":"contributing/wishlist/#tmf-web","title":"TMF WEB","text":""},{"location":"contributing/wishlist/#osom","title":"OSOM","text":"<ul> <li>Actions on service order item and acknowledge order status will define the lifecycle</li> <li>action shutdown on specific date for service order</li> <li>action edit on service order item</li> </ul>"},{"location":"contributing/wishlist/#dynamic-attribute-transformation","title":"Dynamic attribute transformation","text":"<ul> <li>DTM decision tables support per Service Specification</li> <li>Schedule Termination of completed order on running services</li> </ul>"},{"location":"contributing/wishlist/#nfvo-connectivity","title":"NFVO connectivity","text":""},{"location":"contributing/wishlist/#osm-client","title":"OSM Client","text":"<ul> <li>VNF/NSD config params Day 2</li> <li>NSD Lifcecylce</li> <li>NST support</li> </ul>"},{"location":"contributing/wishlist/#nfv-api","title":"NFV API","text":""},{"location":"contributing/wishlist/#nfv-web","title":"NFV WEB","text":""},{"location":"contributing/wishlist/#3rd-party-connectivity","title":"3rd party connectivity","text":""},{"location":"contributing/wishlist/#flowone-connector","title":"FlowOne connector","text":""},{"location":"contributing/wishlist/#openstack-connector","title":"Openstack connector","text":""},{"location":"contributing/wishlist/#kubernetes-connector","title":"Kubernetes connector","text":""},{"location":"contributing/wishlist/#centrallog","title":"CentralLog","text":"<ul> <li>Events from TMF to be written to Central Log</li> </ul>"},{"location":"contributing/wishlist/#authentication","title":"Authentication","text":""},{"location":"naas/exposed_apis/","title":"Supported TMFORUM exposed APIs","text":"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"},{"location":"naas/gst_to_tmf/","title":"Generic Slice Template as a Service Specification","text":""},{"location":"naas/gst_to_tmf/#intended-audience-service-designers","title":"Intended Audience: Service Designers","text":"<p>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</p> <p>Moreove it Proposes standardized Network Slice Templates (NESTs) to target specific use cases</p> <p>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.</p> <p>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.</p> <p></p> <p>The GST to TM Forum via OpenSlice:</p> <pre><code> * 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.\n * TMF Service Specification: Demonstrates the transformation of GST attributes into a TM Forum service specification, showing JSON code snippets that define service parameters.\n * 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.\n</code></pre> <p>What was our flow:</p> <pre><code>* Started with defining service requirements and attributes using GST.\n* Translated these GST attributes into a formal TM Forum service specification.\n* 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.\n</code></pre>"},{"location":"naas/gst_to_tmf/#probe-further","title":"Probe further","text":"<p>See v9 of the GST model in GSMA here</p>"},{"location":"naas/introduction/","title":"Network as a Service (NaaS)","text":"<p>This section describes some core concepts for Delivering Network as a Service in OpenSlice. There are many articles and reports on the subject like:</p> <ul> <li>TMF909 API Suite Specification for NaaS</li> <li>TMF926A Connectivity_as_a_Service </li> <li>TMF931-Open_Gateway_Onboarding_and_Ordering_Component_Suite</li> <li>GSMA Open Gatewy initiative</li> </ul> <p>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.</p>"},{"location":"naas/introduction/#openslice-and-naas","title":"OpenSlice and NaaS","text":"<p>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.</p> <p>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.</p>"},{"location":"naas/introduction/#probe-further","title":"Probe further","text":"<ul> <li>For a complete list of supported APIs, see Supported APIs</li> <li>Check the defined user roles of OpenSlice in our Terminology</li> </ul>"},{"location":"naas/lcm_intro/","title":"Lifecycle Management - LCM","text":"<p>Lifecycle Management: The orchestration framework handles the activation, termination and any necessary modifications throughout the service lifecycle.</p>"},{"location":"naas/lcm_intro/#intended-audience-service-designers","title":"Intended Audience: Service Designers","text":"<p>In OpenSlice the Lifecycle of a service follows in general the concept of Network Slice lifecycle as defined by 3GPP.</p> <p></p>"},{"location":"naas/lcm_intro/#introduction-in-openslice-lcm","title":"Introduction in OpenSlice LCM","text":"<p>OpenSlice adopted the LCM model by 3GPP and mapped to the TMF model service state. Next we discuss briefly the process and the relationships.</p> <p>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. </p> <p>Here is an overview of these stages and relationships with OpenSlice:</p>"},{"location":"naas/lcm_intro/#0-preparation-phase","title":"0. Preparation Phase","text":"<p>This phase is performed by Service Designers</p>"},{"location":"naas/lcm_intro/#service-design","title":"Service Design:","text":"<ul> <li>Requirements Gathering: Collect service requirements from stakeholders, including performance metrics, quality of service (QoS), security needs, and geographical coverage.</li> <li>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).</li> <li>Resource Planning: Identify and plan the required resources, including network functions, computing power, storage, and connectivity, inclluding network function configurations.</li> <li>Expose to Service Catalog: Expose to service catalog for user ordering.</li> </ul> <p>Next phases are handled by the Service Orchestrator after a service is scheduled for instantiation</p> <p>If it is a bundle of services, each services follows its own Lifecycle!</p>"},{"location":"naas/lcm_intro/#1-instantiation-phase","title":"1. Instantiation Phase","text":""},{"location":"naas/lcm_intro/#service-instantiation","title":"Service Instantiation:","text":"<ul> <li>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.</li> <li>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)</li> <li>OpenSlice Service Orchestrator creates the services at \"RESERVED\" state</li> <li>User Notification: There could be an email notification from the system (if Bugzilla is configured)</li> </ul>"},{"location":"naas/lcm_intro/#service-deployment","title":"Service Deployment:","text":"<ul> <li>Activation: OpenSlice Service Orchestrator activates the network service and makes the service available to the end-users. This may involve:</li> <li>Create any related services that the service depends on</li> <li>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)</li> <li>Scheduling instantiation, Resolving dependencies and passing paramemters between controllers,</li> <li>setting up user accounts, provisioning access credentials -this is performed either offline or via other services.</li> <li>OpenSlice Service Orchestrator if everything is succesful puts the service at \"ACTIVE\" state</li> <li>User Notification: There could be an email notification from the system (if Bugzilla is configured)</li> </ul>"},{"location":"naas/lcm_intro/#2-operation-phase","title":"2. Operation Phase","text":""},{"location":"naas/lcm_intro/#service-operation","title":"Service Operation:","text":"<ul> <li>Lifecycle Management: Manage the network slice throughout its lifecycle, including scaling, reconfiguration, and adaptation to changing requirements. </li> <li>In OpenSlice this is performed with Lifecycle management Rules (see next)</li> </ul> <p>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:</p> <ul> <li>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.</li> <li>Maintenance: Conduct regular maintenance activities, including software updates, patching, and optimization to ensure the service runs smoothly.</li> <li>Scaling: Dynamically scale the resources up or down based on the demand and performance requirements.</li> <li>Fault Management: Detect and resolve faults in the network slice to minimize downtime and maintain service quality.</li> </ul>"},{"location":"naas/lcm_intro/#3-decommissioning-phase","title":"3. Decommissioning Phase","text":"<ul> <li>Service Termination: Service Orchestrator terminates the network service. This may involve:</li> <li>Terminate any related services that the service depends on</li> <li>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)</li> <li>Scheduling termination, Resolving dependencies and passing paramemters between controllers</li> <li>OpenSlice Service Orchestrator, if everything is succesful, puts the service at \"TERMINATED\" state</li> <li>User Notification: There could be an email notification from the system (if Bugzilla is configured)</li> </ul>"},{"location":"naas/lcm_intro/#high-level-example-enhanced-mobile-broadband-embb-service-lifecycle","title":"High level example: Enhanced Mobile Broadband (eMBB) Service Lifecycle","text":"<ol> <li> <p>Preparation:</p> </li> <li> <p>Define eMBB service requirements for high bandwidth and low latency.</p> </li> <li>Create an eMBB service specification template specifying related services and resources to Kubernetes Operators, VNFs for content delivery and traffic management.</li> <li> <p>Expose to catalog</p> </li> <li> <p>Instantiation:</p> </li> <li> <p>Instantiate other services and allocate resources such as edge computing nodes and high-capacity links.</p> </li> <li> <p>Configure the service to prioritize video streaming traffic.</p> </li> <li> <p>Operation:</p> </li> <li> <p>Monitor the service to ensure it meets high-bandwidth requirements.</p> </li> <li> <p>Scale up resources during peak usage periods, such as live sports events.</p> </li> <li> <p>Decommissioning:</p> </li> <li> <p>Notify users about service termination.</p> </li> <li>Decommission the network service, reclaiming resources for other services.</li> </ol>"},{"location":"naas/lcm_intro/#probe-further","title":"Probe further","text":"<ul> <li>See 3GPP Lifecycle</li> </ul>"},{"location":"naas/lcm_rules_intro/","title":"Lifecycle Management Rules - LCM Rules","text":"<p>Lifecycle Management Rules: Defining complex conditions and actions during the lifecycle of a service and any necessary modifications throughout the service lifecycle.</p>"},{"location":"naas/lcm_rules_intro/#intended-audience-service-designers","title":"Intended Audience: Service Designers","text":"<p>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)</p> <p>So in the system there are already predefined recipes, which in each process-step of the workflow some piece of code is executed. </p> <p>How is it possible to intervene in the workflow process and inject some user defined actions? The next image illustrates the idea</p> <p></p>"},{"location":"naas/lcm_rules_intro/#how-is-it-possible-to-intervene-in-the-workflow-process-and-affect-it","title":"How is it possible to intervene in the workflow process and affect it?","text":"<p>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:</p> <ul> <li>PRE_PROVISION</li> <li>CREATION</li> <li>AFTER_ACTIVATION </li> <li>SUPERVISION </li> <li>AFTER_DEACTIVATION </li> </ul> <p>The following figure displays the different phases that the rules are performed, during the lifecycle of a Network Service Instance. </p> <p></p> <ul> <li>PRE_PROVISION rules: Run only once just before creating a service with a given priority. </li> <li>CREATION rules: Run while the referenced service dependencies of a service are created</li> <li>AFTER_ACTIVATION rules: Run only once just after a service get the ACTIVE state</li> <li>SUPERVISION rules: Run when a characteristic of a service is changed and the service is in the ACTIVE state </li> <li>AFTER_DEACTIVATION rules: Run only once just after a service get the INACTIVE/TERMINATED state </li> </ul> <p>In general the rules allow to perform many actions during service LCM. These are some examples:</p> <ul> <li>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</li> <li>Translate GST/NEST parameter values to other values passed later to NFVO for instantiation or control</li> <li>Define complex OSM Configs based on other dependencies and passing variables</li> <li>Define any dependencies when creating the referenced services</li> <li>Dynamically include new service dependencies</li> <li>Create new service orders so include dynamically other services</li> <li>Call external (RESTful) services (via http(s), define payload, examine response)</li> </ul>"},{"location":"naas/lcm_rules_intro/#examine-if-the-rules-are-executed-successfully","title":"Examine if the rules are executed successfully","text":"<p>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.</p>"},{"location":"naas/lcm_rules_intro/#probe-further","title":"Probe further","text":"<ul> <li>In the Service Design section we present in details the Lifecycle rules and how one can design them</li> <li>Many of them are used in our provided Service Design examples</li> </ul>"},{"location":"naas/resource_catalog/","title":"OpenSlice Resource Catalog:","text":"<pre><code>* Resource Specifications: Defines the underlying resources required to deliver services, such as network components, servers, and software.\n* Resource Availability: Tracks the availability and status of resources to ensure efficient service delivery.\n</code></pre>"},{"location":"naas/service_catalog/","title":"OpenSlice Service Catalogs","text":"<p>OpenSlice offers complete management of Service Catalogs.</p>"},{"location":"naas/service_catalog/#intended-audience-service-designers-openslice-administrators-users","title":"Intended Audience: Service Designers, OpenSlice administrators, Users","text":"<p>OpenSlice offers complete management of Service Catalogs which offer to end users:</p> <ul> <li>Service categories: Lists the available services, including their specifications and performance metrics.</li> <li>Service Bundles: Combines multiple services into a single offering to provide added value to customers.</li> </ul> <p>Service Catalogs contain Service Specifications (organized in Service Categories) exposed to users for Service Orders.</p>"},{"location":"naas/service_catalog/#ui-management","title":"UI management","text":"<p>In the UI this looks like the following. Service catalogs and categories exposed in Service marketplace. </p> <p>In the menu the administrator can manage the Service Catalogs and Categories.</p> <p></p>"},{"location":"naas/service_catalog/#api-exposed","title":"API exposed","text":"<p>When installing OpenSlice the API endpoints can be browsed at: </p> <pre><code>[YOURDOMAIN]/tmf-api/swagger-ui/index.html?urls.primaryName=tmf-api-633-ServiceCatalogManagement-v4.0.0\n\nendpoint examples:\n\n/serviceCatalogManagement/v4/serviceCatalog List or find ServiceCatalog objects\n/serviceCatalogManagement/v4/serviceCategory List or find ServiceCategory objects\n\n</code></pre>"},{"location":"naas/service_catalog/#example-use-case","title":"Example Use Case","text":"<p>Scenario: A service provider wants to offer a new managed XXXX service to enterprise customers.</p> <ul> <li>Service Definition: Service Template thus create a template for the XXXX service, including specifications for bandwidth, network features, and performance metrics.</li> <li>Service Catalog Integration: Add to Service Catalog the XXXX service with all relevant details.</li> <li>Service Delivery/Order: Provision Service by Using the orchestration system to provision and configure the XXXX service based on customer orders.</li> </ul>"},{"location":"naas/service_catalog/#probe-further","title":"Probe further","text":"<ul> <li>Read the model of Service Catalogs in TMF TMF633 Service Catalog API User Guide v4.0.0</li> <li>Check a demo of the API here</li> <li>Check a demo of the Catalog and Categories here</li> </ul>"},{"location":"naas/service_inventory/","title":"Service Inventory","text":"<p>Service Inventory contains refences to running services that realize a Service Order</p>"},{"location":"naas/service_inventory/#intended-audience-service-designers-openslice-administrators-users","title":"Intended Audience: Service Designers, OpenSlice administrators, Users","text":"<p>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. </p> <p>This inventory enables real-time visibility into the status, configuration, and dependencies of each service, facilitating effective management, troubleshooting, and optimization. </p> <p>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 inital requst. </p>"},{"location":"naas/service_inventory/#ui-management","title":"UI management","text":"<p>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.</p>"},{"location":"naas/service_inventory/#api-exposed","title":"API exposed","text":"<p>When installing OpenSlice the API endpoints can be browsed at: </p> <pre><code>[YOURDOMAIN]/tmf-api/swagger-ui/index.html?urls.primaryName=tmf-api-638-ServiceInventoryManagement-v4.0.0\n</code></pre> <p>endpoint examples:</p> <p>/serviceInventory/v4/service List or find Service objects</p>"},{"location":"naas/service_inventory/#probe-further","title":"Probe further","text":"<ul> <li>See Ordering Services from catalogs</li> <li>See Service Design</li> </ul>"},{"location":"naas/service_ordering/","title":"Service Ordering","text":"<p>Customer Facing Service Specifications - or also CFSSpec (organized in Service Categories) are exposed to users for Service Orders.</p>"},{"location":"naas/service_ordering/#intended-audience-service-designers-openslice-administrators","title":"Intended Audience: Service Designers, OpenSlice administrators","text":"<p>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 bunlde), 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.</p> <p>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. </p> <p>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.</p> <p>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.</p> <p>Ongoing monitoring and other actions can be performed by the Life Cycle management rules</p> <p>Future developments: In future releases it might be possible the ongoing monitoring and support provided to ensure continuous performance and reliability. The service could undergoe a series of tests to ensure it meets the specified performance metrics and SLAs before delivering</p>"},{"location":"naas/service_ordering/#ui-management","title":"UI management","text":"<p>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.</p>"},{"location":"naas/service_ordering/#api-exposed","title":"API exposed","text":"<p>When installing OpenSlice the API endpoints can be browsed at: </p> <pre><code>[YOURDOMAIN]/tmf-api/swagger-ui/index.html?urls.primaryName=tmf-api-641-ServiceOrdering-v4.0.0\n</code></pre> <p>endpoint examples:</p> <p>/serviceOrdering/v4/serviceOrder List or find ServiceOrder objects</p>"},{"location":"naas/service_ordering/#probe-further","title":"Probe further","text":"<ul> <li>See Ordering Services from catalogs</li> <li>See Service Design</li> </ul>"},{"location":"naas/service_spec/","title":"OpenSlice Service Specification","text":"<p>OpenSlice offers complete management of Service Specifications.</p>"},{"location":"naas/service_spec/#intended-audience-service-designers","title":"Intended Audience: Service Designers","text":"<p>Service Specification is an entity that describes a service offering. There are two types of Service Specifications:</p> <ul> <li>Resource Facing Service Specification</li> <li>Customer Facing Service Specification</li> </ul>"},{"location":"naas/service_spec/#resource-facing-service-specification","title":"Resource Facing Service Specification","text":"<p>Is a Service that It exposes a resource Specification as a Service. (For example expose a Network Service Descriptor as a Service)</p>"},{"location":"naas/service_spec/#customer-facing-service-specification","title":"Customer Facing Service Specification","text":"<p>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</p>"},{"location":"naas/service_spec/#definition","title":"Definition","text":"<p>Usually a Service Specification has the following aspects:</p> <ul> <li>Name, Description, Version</li> <li>Marked as a Service Bundle: Combines multiple services into a single offering to provide added value to customers.</li> <li>if is is a Bundle then you must add Related Service Specifications</li> <li>If it is a Resource Facing Service Specification has multiple related Resource Facing Service Specifications</li> <li>Characteristics: a list of service characteristics and their type (TEXT, INTEGER, etc)</li> <li>Also they can be exposed as \"Configurable\" so to allow to end-users during the Service Order to select or type values</li> <li>A logo, displayed if needed in the Service Marketplace</li> <li>Any attachments that further help the user</li> <li>Life Cycle Rules that determine the behavior of the Service and instrument the Service Orchestrator. More on Life Cycle Rules here</li> </ul> <p>Service Designers can create a Service Specification from scratch or use some templates:</p> <pre><code>* Create a Service based from a Network Service Descriptor (NSD)\n* Create a Service based on a Kubernetes Operator\n* Create a Service based on the GSMA GST - Generic Slice Template\n</code></pre>"},{"location":"naas/service_spec/#ui-management","title":"UI management","text":"<p>In the UI this looks like the following.</p> <p>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.</p>"},{"location":"naas/service_spec/#api-exposed","title":"API exposed","text":"<p>When installing OpenSlice the API endpoints can be browsed at: </p> <pre><code>[YOURDOMAIN]/tmf-api/swagger-ui/index.html?urls.primaryName=tmf-api-633-ServiceCatalogManagement-v4.0.0\n</code></pre> <p>endpoint examples:</p> <p>/serviceCatalogManagement/v4/serviceSpecification List or find ServiceSpecification objects</p>"},{"location":"naas/service_spec/#example-use-case","title":"Example Use Case","text":"<p>Scenario: A service provider wants to offer a new managed XXXX service to enterprise customers.</p> <ul> <li>Service Definition: Create a service specification template for the XXXX service, including specifications for bandwidth, network features, and performance metrics.</li> </ul>"},{"location":"naas/service_spec/#probe-further","title":"Probe further","text":"<ul> <li>Read the model of Service Catalogs in TMF TMF633 Service Catalog API User Guide v4.0.0</li> <li>Check a demo of the API here</li> <li>Check a demo of the Service Specifications in Catalog and Categories here (You need to login - see main guide page)</li> <li>Check the GSMA GST</li> </ul>"},{"location":"naas/so_intro/","title":"Service Orchestration","text":"<ul> <li>Service Orchestration: 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.</li> </ul>"},{"location":"naas/so_intro/#intended-audience-service-designers","title":"Intended Audience: Service Designers","text":"<p>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.</p> <p>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)</p> <p></p> <p>This section provides a high level overview of the Service Orchestration process.</p>"},{"location":"naas/so_servicespec_to_services_nfv/","title":"From Service Specification to NFV based services","text":"<p>After a Service Order completion, active services with their additional characteristics are found:</p> <ul> <li>From the Order Items of a selected Service order</li> <li>from the menu of Service inventory and then selecting details of each service</li> <li>through the Service Inventory API (TMF 638 - Service Inventory Management ) </li> </ul> <p>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. </p> <p></p> <p>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</p>"},{"location":"naas/so_servicespec_to_services_nfv/#interacting-with-an-active-service-day-2-config","title":"Interacting with an Active Service (Day 2 config)","text":"<p>In some cases, if the underlying service is configured with actions (for example in OSM Day 2 primitive actions), there are characteristics that can be modified. Usually they are named like : ::Primitive:: <p>The user can edit the characteristic with a new value. The value is propagated through the OSOM and NFVO down to the related VNF.</p>"},{"location":"naas/so_servicespec_to_services_nfv/#terminatinginactivating-a-service","title":"Terminating/Inactivating a service","text":"<p>You can terminate the service with one of the following processes:</p> <ul> <li>Select the related Service Order and terminate the Order Item. This will delete all the underlying related active services. The Order goes to ACKNOWLEDGED->INPROGRESS->COMPLETE</li> <li>To terminate or inactivate a service, select the specific service from the inventory, press Edit and set the State either to Inactive or Terminated</li> </ul> <p>Warning: if you terminate or inactivate a service the action cannot be undone. </p>"},{"location":"naas/so_servicespec_to_services_nfv/#uml-sequence-diagram","title":"uml: sequence diagram","text":"<p>Here I will embed PlantUML markup to generate a sequence diagram.</p> <p>I can include as many plantuml segments as I want in my Markdown, and the diagrams can be of any type supported by PlantUML.</p>"},{"location":"naas/nfv/nfvservices/","title":"NFV Services","text":"<p>NFV Services are managed through a dedicate UI the NFV portal (eg http://portal.openslice.io/nfvportal)</p> <p>Users are able through this portal to manage their NFV artifacts towards the NFVO, ( for example onboard VNFs and NSDs to a target OSM)</p> <p>Openslice NFV Services target to accommodate the following envisaged user roles. All users are assumed to be Authenticated:</p> <ul> <li>NFV developer: This role is responsible to upload VNF and NSD Descriptors in the Openslice services towards NFVO like OSM</li> <li>Services administrator: This role represents the user that are responsible for maintenance of the Openslice services</li> </ul> <p>(obsolete: )</p> <ul> <li>Testbed provider: This role represents users that are responsible for testbed administration, configuration, integration, adaptation, support, etc</li> <li>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)</li> </ul> <p>Finally an anonymous user role exists who has some really simple usage scenarios (e.g. signup through the portal)</p> <p>During the onboarding process the following occurs:</p> <p>\u2022 A NFV developer submits a NFV archive (VNF or NSD) (he can later manage if needed some metadata) \u2022 The administrator can manage the NFV artifact (e.g. edit it) \u2022 The administrator On-Boards the NFV artifact to the target MANO \u2022 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</p>"},{"location":"naas/nfv/nfvservices/#request-a-new-nsd-deployment-this-is-different-in-comparison-to-services","title":"Request a new NSD deployment (this is different in comparison to Services)","text":"<p>A developer requests a new network service deployment (which NSD, tentative dates, target infrastructure, etc.). The request is marked as UNDER_REVIEW</p> <ul> <li>The administrator is notified about the new request and he has the following options:</li> <li>Schedule the deployment for the requested dates or propose other dates. The request is marked as SCHEDULED</li> <li>Reject the request for some reason. The Request is marked as REJECTED</li> <li>Deploy the request to target VIM(s). The Request is marked as RUNNING</li> <li>Finalize the deployment and release resources. The Request is marked as COMPLETED</li> <li>every change of the request-lifecycle the experimenter is notified.</li> </ul>"},{"location":"service_design/catalogs/","title":"Catalogs and Templates","text":"<p>The Openslice Service Catalogue (accessible through the API or Services portal) contains the representation of Service Specifications, either created from the provider defining service attributes, or by supporting the GSMA Generic Slice Templates (GST) as well as the VINNI Service Blueprint. The following scenarios are supported by the Openslice Service Catalogue.</p>"},{"location":"service_design/catalogs/#createdesign-a-service-specification","title":"Create/Design a Service Specification","text":""},{"location":"service_design/catalogs/#first-import-some-resources-as-resource-facing-services-rfss","title":"First Import some Resources as Resource Facing Services (RFSs)","text":"<p>If you have any NSDs as NFV artifacts, import them through the UI menu (Import from NSD list). Then an NSD is imported as a resource and an RFS automatically is created. RFSs then later are used to design a Customer Facing Service Specification</p>"},{"location":"service_design/catalogs/#createdesign-a-customer-facing-service-specification","title":"Create/Design a Customer Facing Service Specification","text":"<p>Customer Facing Service Specification are the services offered to customers. You can create a new Service Specification from the menu. The services created through the UI are Customer Facing Services (CFS). Usually you create a CFS as a bundle and then you include Service Specification Relationships with RFSs or/and CFSs.</p> <p>Any Service Specification Characteristics from the RFS are copied to the CFS specification. A CFS can include multiple RFS or/and CFSs. For example you can create a CFS spec called \"A 5G Service\" which is a bundle of two other services (include them in Service Specification Relationships) such as 5G eMBB Slice and a Customer VPN. So when the user orders \"A 5G Service\" services from 5G eMBB Slice and a Customer VPN will be created during the order.</p>"},{"location":"service_design/catalogs/#initial-configuration-for-osm-deployment","title":"Initial configuration for OSM deployment","text":"<p>if you have an initial configuration that needs to be applied in the NSD deployment, then you go to the RFS (or CFS) and in Service Specification Characteristics go and edit the OSM_CONFIG characteristic. You can add in the Service Characteristic Value, in the Value field something like the following example which gives a floating IP to a VNF:</p> <pre><code>{ \"nsdId\": \"e855be91-567b-45cf-9f86-18653e7ea\", \"vimAccountId\": \"4efd8bf4-5292-4634-87b7-7b3d49108\" , \"vnf\": [ {\"member-vnf-index\": \"1\", \"vdu\": [ {\"id\": \"MyCharmedVNF-VM\", \"interface\": [{\"name\": \"eth0\", \"floating-ip-required\": true }]}]}]}\n\n</code></pre> <p>or a more complex example (beautify it first if you want to view it, but in the parameter OSM_CONFIG must be minified like the example):</p> <pre><code>{\"nsdId\":\"e855be91-567b-45cf-9f86-18653e7\",\"vimAccountId\":\"4efd8bf4-5292-4634-87b7-7b3d491\",\"vnf\":[{\"member-vnf-index\":\"1\",\"vdu\":[{\"id\":\"haproxy_vdu\",\"interface\":[{\"name\":\"haproxy_vdu_eth1\",\"floating-ip-required\":true}]}]}],\"vld\":[{\"name\":\"pub_net\",\"vim-network-name\":\"OSMFIVE_selfservice01\"},{\"name\":\"management\",\"vim-network-name\":\"OSMFIVE_selfservice01\"},{\"name\":\"lba_net\",\"vim-network-name\":\"lba_net\",\"vnfd-connection-point-ref\":[{\"member-vnf-index-ref\":\"1\",\"vnfd-connection-point-ref\":\"haproxy_private\",\"ip-address\":\"192.168.28.2\"}]},{\"name\":\"backend_net\",\"vim-network-name\":\"backend_net\",\"vnfd-connection-point-ref\":[{\"member-vnf-index-ref\":\"3\",\"vnfd-connection-point-ref\":\"haproxy_public\",\"ip-address\":\"192.168.20.2\"}]},{\"name\":\"lb_sb_net\",\"vim-network-name\":\"lb_sb_net\",\"vnfd-connection-point-ref\":[{\"member-vnf-index-ref\":\"3\",\"vnfd-connection-point-ref\":\"haproxy_private\",\"ip-address\":\"192.168.28.2\"}]},{\"name\":\"breaking_point_Spain\",\"vim-network-name\":\"sb_repo_net\"},{\"name\":\"breaking_point_Greece\",\"vim-network-name\":\"5TONICexternal\"}],\"additionalParamsForVnf\":[{\"member-vnf-index\":\"2\",\"additionalParams\":{\"target_IP\":\"192.168.20.2\"}},{\"member-vnf-index\":\"4\",\"additionalParams\":{\"target1_IP\":\"192.168.21.2\",\"target2_IP\":\"10.154.252.10\"}}]}\n</code></pre> <p>You can leave the Alias and Unit of Measure as is. Check also the is Default.</p>"},{"location":"service_design/catalogs/#day-2-primitive-actions","title":"Day 2 Primitive Actions","text":"<p>NFVOs like OSM allow to perform actions while a service is running, for example change attributes or make actions on a specific VNF. To design this do something similar to the following example:</p> <ul> <li>Go to the RFS related to the NSD that contains VNFs with primitives</li> <li>create a characteristic named Primitive:: , e.g. Primitive::touch <li>select Value Type: ARRAY</li> <li>add Service Characteristic Value: i) alias=primitive, value= (e.g. touch), ii) alias=member_vnf_index, value= (e.g. 1), iii) add the params that the user will change in alias the name of param and in value an initial value (e.g. alias=filename, value=myfile.txt) <p>In the above example, when the service is running and the user goes to service inventory to MODIFY it, changes the value of the alias=filename, value=myfile.txt, to value =secondfile.txt. Then inside the VNF a file will be created called secondfile.txt</p>"},{"location":"service_design/catalogs/#generic-slice-templates-gst","title":"Generic Slice Templates (GST)","text":"<p>(Offered only as a design for now. THere is no direct implementation to NFV) On October 16th 2019 GSMA published NG.116 Version 2.0 which defines the Generic Network Slice Template (GST). GST is a set of attributes that can characterise a type of network slice/service. GST is generic and is not tied to any specific network deployment. Here is a list of the various attributes of the template:</p> <ul> <li>Availability</li> <li>Area of Service</li> <li>Delay tolerance</li> <li>Deterministic communication</li> <li>Downlink throughput per network slice</li> <li>Downlink throughput per UE</li> <li>Energy efficiency</li> <li>Group communication support</li> <li>Isolation level</li> <li>Location based message delivery</li> <li>Maximum supported packet size</li> <li>Mission critical support</li> <li>MMTel support</li> <li>NB-IoT support</li> <li>Network Slice Customer network functions</li> <li>Number of connections</li> <li>Number of terminals</li> <li>Performance monitoring</li> <li>Performance prediction</li> <li>Positioning support</li> <li>Radio spectrum</li> <li>Reliability</li> <li>Root cause investigation</li> <li>Session and Service Continuity support </li> <li>Simultaneous use of the network slice</li> <li>Slice quality of service parameters</li> <li>Support for non-IP traffic </li> <li>Supported access technologies </li> <li>Supported device velocity </li> <li>Synchronicity</li> <li>Terminal density </li> <li>Uplink throughput per network slice </li> <li>Uplink throughput per UE</li> <li>User management openness</li> <li>User data access </li> <li>V2X communication mode</li> </ul> <p>Openslice offers the GST in a format that is machine readable and aligned with the TMF SID model. Here is a tentative approach in JSON : https://github.com/openslice/org.etsi.osl.tmf.api/blob/master/src/main/resources/gst.json</p> <p>Providers can clone a GST as e NEST directly in Openslice Web portal and the adjust the default attributes to their Service Specification</p>"},{"location":"service_design/catalogs/#manage-a-service-specification","title":"Manage a Service Specification","text":"<p>You can manage them though the Web UI</p>"},{"location":"service_design/catalogs/#assign-a-service-specification-to-service-categories-and-publish","title":"Assign a Service Specification to Service Categories and Publish","text":"<p>Just create categories and from the menu select the category and add services</p>"},{"location":"service_design/catalogs/#retireremove-a-service-specification","title":"Retire/Remove a Service Specification","text":"<p>Delete it from the category</p>"},{"location":"service_design/catalogs/#consume-and-expose-service-specifications-from-other-service-catalogues","title":"Consume and expose Service Specifications from other Service Catalogues","text":"<p>See more on Consuming Services From External Partner Organizations</p>"},{"location":"service_design/intro/","title":"Service Design in OpenSlice","text":"<p>This section offers details on how to design Service Specifications and expose them in Service Catalogs</p>"},{"location":"service_design/intro/#intended-audience-service-designers","title":"Intended Audience: Service Designers","text":"<p>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.</p> <p>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.</p>"},{"location":"service_design/intro/#probe-further","title":"Probe further","text":"<ul> <li>Design and expose services based on containerized resources via the Kubernetes Operator pattern</li> <li>Design and expose services based on NFV artifacts</li> </ul>"},{"location":"service_design/examples/ExposingCRDs_aaS_Example_Calculator/ExposingCRDs_aaS_Example_Calculator/","title":"Exposing Kubernetes Operators as a Service : Offering \"Calculator as a Service\" through OpenSlice","text":""},{"location":"service_design/examples/ExposingCRDs_aaS_Example_Calculator/ExposingCRDs_aaS_Example_Calculator/#intended-audience-service-designers","title":"Intended Audience: Service Designers","text":"<p>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.\" </p> <p>This example will demonstrate the flexibility and capabilities of Kubernetes operators in managing custom resources and automating operational tasks.</p>"},{"location":"service_design/examples/ExposingCRDs_aaS_Example_Calculator/ExposingCRDs_aaS_Example_Calculator/#offering-calculator-as-a-service-through-openslice","title":"Offering \"Calculator as a Service\" through OpenSlice","text":"<ul> <li>We have a service that can accept two integers and an action (SUM, SUB, etc) and returns a result</li> <li>We would like to offer it as a Service through OpenSlice</li> <li>So when a user orders it with some initial parameters, OpenSlice will create it and return the result</li> <li>Also while the service is active, we can do further calculations, until we destroy it.</li> </ul> <p>Assume the following simple CRD of a calculator model accepting two params (spec section) and an action and returning a result (status section)</p> <p>The controller (the calculator code) is implemented in any language and is installed in a Kubernetes cluster</p> <pre><code>\napiVersion: apiextensions.k8s.io/v1\nkind: CustomResourceDefinition\nmetadata:\n name: mycalculators.examples.osl.etsi.org\nspec:\n group: examples.osl.etsi.org\n names:\n kind: MyCalculator\n plural: mycalculators\n singular: mycalculator\n scope: Namespaced\n versions:\n - name: v1alpha1\n schema:\n openAPIV3Schema:\n properties:\n spec:\n properties:\n parama:\n type: integer\n paramb:\n type: integer\n action:\n type: string\n type: object\n status:\n properties:\n result:\n type: integer\n status:\n type: string\n type: object\n type: object\n served: true\n storage: true\n subresources:\n status: {}\n</code></pre> <p>Request to the cluster (through e.g. kubectl apply)</p> <pre><code>apiVersion: examples.osl.etsi.org/v1alpha1\nkind: MyCalculator\nmetadata:\n name: mycalculator.examples.osl.etsi.org\nspec:\n parama: 170\n paramb: 180\n action: 'SUM'\n\n</code></pre> <p>Response</p> <pre><code>apiVersion: examples.osl.etsi.org/v1alpha1\nkind: MyCalculator\nmetadata:\n\u00a0 creationTimestamp: '2023-12-05T12:26:07Z\u2019\n\n<snip>\n\nstatus:\n\u00a0 result: 350\n\u00a0 status: CALCULATED\nspec:\n\u00a0 action: SUM\n\u00a0 parama: 170\n\u00a0 paramb: 180\n\n</code></pre> <p>To perform this through OpenSlice as a Service Specification ready to be ordered we need to do the following:</p>"},{"location":"service_design/examples/ExposingCRDs_aaS_Example_Calculator/ExposingCRDs_aaS_Example_Calculator/#crd-is-saved-automatically-as-resource-specification","title":"CRD is saved automatically as Resource Specification","text":"<p>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.</p> <ul> <li>See also the fully qualified name of the resource specification. <ul> <li>MyCalculator@examples.osl.etsi.org/v1alpha1@docker-desktop@https://kubernetes.docker.internal:6443/</li> <li>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:<ul> <li>MyCalculator@examples.osl.etsi.org/v1alpha1@default_cluster@https://10.10.10.8:6443/</li> <li>MyCalculator@examples.osl.etsi.org/v1alpha1@edge1_cluster@https://172.16.10.10:6443/</li> </ul> </li> <li>Having this OpenSlice can manage resources in multiple clusters</li> </ul> </li> </ul> <p></p> <p>See also the detailed characteristics. See how OpenSlice makes all characteristics automatically flat and expanded with key-value style</p> <p></p>"},{"location":"service_design/examples/ExposingCRDs_aaS_Example_Calculator/ExposingCRDs_aaS_Example_Calculator/#expose-to-users","title":"Expose to Users","text":""},{"location":"service_design/examples/ExposingCRDs_aaS_Example_Calculator/ExposingCRDs_aaS_Example_Calculator/#start-by-creating-a-resourcefacingservicespecification","title":"Start by Creating a ResourceFacingServiceSpecification","text":"<p>From the UI menu create a new Service Specification</p> <p></p> <p></p>"},{"location":"service_design/examples/ExposingCRDs_aaS_Example_Calculator/ExposingCRDs_aaS_Example_Calculator/#creation-of-crd-related-characteristics","title":"Creation of CRD-related characteristics","text":"<ul> <li>We need now to adjust some characteristics of this CRD as Resource Specification.</li> <li>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</li> <li> <p>We need to make OpenSlice aware of when the service will be active. </p> <ul> <li>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) </li> <li>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\"</li> <li>We need also to define the yaml file that OpenSLice will use to create the new resource in the kubernetes cluster</li> <li>We insert the YAML in the characteristic _CR_SPEC</li> </ul> <p>the _CR_SPEC is: </p> </li> </ul> <pre><code>apiVersion: examples.osl.etsi.org/v1alpha1\nkind: MyCalculator\nmetadata:\n name: mycalculator.examples.osl.etsi.org\nspec:\n parama: 170\n paramb: 180\n action: 'SUM'\n\n</code></pre> <p></p> <p>However the values are fixed. How do we allow a user to pass parameters through OpenSlice</p>"},{"location":"service_design/examples/ExposingCRDs_aaS_Example_Calculator/ExposingCRDs_aaS_Example_Calculator/#expose-in-catalog","title":"Expose in Catalog","text":"<p>Create a new CustomerFacingServiceSpecification</p> <pre><code>- Go to the menu Service Specification>New Service Specification\n- Create a service My Calulator and mark it as a Bundle\n- Go to Service Specification Relationships and add MyCalculatorRFS\n- The service will be automatically transformed to a \"CustomerFacingServiceSpecification\"\n- Add the following characteristics as the image shows:\n</code></pre> <p></p>"},{"location":"service_design/examples/ExposingCRDs_aaS_Example_Calculator/ExposingCRDs_aaS_Example_Calculator/#allow-users-to-pass-new-values-through-openslice","title":"Allow users to pass new values through OpenSlice","text":"<p>We need to Create LCM rules in CustomerFacingServiceSpecification:</p> <pre><code>- The goal of the rules is to allow the user to pass parameters to the actual resource towards the cluster.\n- we will create one rule that will pass the parameters just before creating the service (PRE_PROVISION phase)\n- we will create one rule that will pass the parameters while the service is active (SUPERVISION phase)\n- The rules will be the same\n</code></pre> <p></p> <p>If we see one rule it will look like the following:</p> <p></p> <ul> <li>We need to change the _CR_SPEC characteristic of the referenced ResourceFacingServiceSpecification</li> <li>First bring a block from Service>Relationships>Service Refs and drop the \"Service MyCalculatorRFS\" block</li> <li>Then add a list block from Lists</li> <li>Then add the block that modifies a referenced characteristic from Service>Relationships>Service Refs the block \"Set value to characteristic of a Referenced Service\"</li> <li>Add a block for text _CR_SPEC </li> <li>We use a block that changes a String according to variables Text>\"A formatted text replacing variables from List\"</li> <li>See that we have as Input string the YAML string lines<ul> <li>see that parama, paramb has a %d (they accept integers), action is %s (accepts a string)</li> <li>See that the variables tha will replace the %d, %d and %s are an list<ul> <li>the first %d will be replaced with the value from characteristic spec.parama</li> <li>the second %d will be replaced with the value from characteristic spec.paramb</li> <li>the %s will be replaced with the value from characteristic spec.action</li> </ul> </li> </ul> </li> </ul> <p>If we see the SUPERVISION rule it will look like the following:</p> <ul> <li>It contains also the Result field, which takes the value from the referenced service</li> <li>Add a block for the Result field from Service>Number blocks</li> <li>Add a str to int block from Number blocks</li> <li>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\"</li> <li>Add as name the \"status.result\" </li> </ul> <p></p> <p></p> <p>Expose it then to a catalogue for orders through the Service Categories and Service Catalogs</p> <p></p>"},{"location":"service_design/examples/ExposingCRDs_aaS_Example_Calculator/ExposingCRDs_aaS_Example_Calculator/#order-the-service","title":"Order the Service","text":"<p>When a user orders the service, it will look like this:</p> <p></p> <ul> <li>After the Service Order we have 2 services in service inventory on CFS and on RFS. Both have references to values</li> <li>OpenSlice (via CRIDGE service) updates the Resource in Resource Inventory and OSOM updates the Services in Service Inventory</li> <li>The Actual resources are running in the Kubernetes cluster managed by OpenSlice</li> <li>The result is in the characteristic status.result of the running service</li> </ul> <p></p> <p></p>"},{"location":"service_design/examples/ExposingCRDs_aaS_Example_Calculator/ExposingCRDs_aaS_Example_Calculator/#modify-the-running-service","title":"Modify the running service","text":"<p>The user can modify the service</p> <p></p> <ul> <li>After a while the update is applied to the cluster, the controller will pick up the resource update and patch the resource</li> <li>OpenSlice (via CRIDGE service) updates the Resource in Resource Inventory and OSOM updates the Services in Service Inventory</li> <li>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)</li> </ul> <p></p>"},{"location":"service_design/kubernetes/ExposingKubernetesResources/","title":"Expose and manage Kubernetes Custom Resource Definitions (Operators) in a Kubernetes Cluster","text":"<p>OpenSlice is capable of exposing Kubernetes Resources and Definitions as Service Specifications</p>"},{"location":"service_design/kubernetes/ExposingKubernetesResources/#intended-audience-service-designers","title":"Intended Audience: Service Designers","text":"<p>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.</p> <p>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.</p> <ol> <li> <p>OpenSlice is capable to:</p> <ul> <li>Create and manage Custom Resources (CRs) using installed CRDs on a target Kubernetes cluster.</li> <li>Facilitate complex orchestration scenarios by wrapping Kubernetes APIs as TMF APIs and models.</li> <li>Handles connectivity to a Kubernetes cluster and manages the lifecycle of CRDs</li> <li>Wraps the Kubernetes API, Receives and provides resources towards other OpenSlice services via the service bus</li> </ul> </li> <li> <p>Enabling Loose Coupling and Orchestration</p> <ul> <li>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.</li> <li>Familiar Deployment: Developers can create and deploy applications using familiar tools such as Helm charts, simplifying the process and reducing the learning curve.</li> </ul> </li> <li> <p>Ecosystem Reusability</p> <ul> <li>OpenSlice capitalizes on the extensive Kubernetes ecosystem, particularly focusing on operators (CRDs).</li> <li>Key repositories and hubs such as artifacthub.io and Operatorhub.io can be utilized for finding and deploying operators.</li> </ul> </li> <li> <p>Service Catalog Exposure and Deployment</p> <ul> <li>OpenSlice can expose CRs in service catalogs, facilitating their deployment in complex scenarios.</li> <li>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.</li> </ul> </li> </ol>"},{"location":"service_design/kubernetes/ExposingKubernetesResources/#approach","title":"Approach","text":"<p>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.</p> <p>The following image illustrates the approach.</p> <p></p> <ol> <li>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</li> <li>Service Orders can be created for this service specification. </li> <li>OSOM creates a Resource in OSL Resource inventory and requests new Custom Resource (CR) in the target cluster<ul> <li>The resource is created in a specific namespace (for example the UUID of the Service Order)</li> <li>A CR in a cluster will be mapped in TMF model as a Resource in the resource Inventory</li> <li>Other related resources created by the CRD Controller within the namespace are automatically created in OSL Resource Inventory under the same Service Order</li> </ul> </li> </ol>"},{"location":"service_design/kubernetes/ExposingKubernetesResources/#awareness-for-crds-and-crs-in-cluster","title":"Awareness for CRDs and CRs in cluster","text":"<p>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.</p> <p>When installing OpenSlice you can configure at least one management cluster. OpenSlice connects via a provided kubeconf</p> <ul> <li>On Start up OSL tries to register this cluster and context to OSL catalogs.</li> <li>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</li> <li>Resources created by OpenSlice have labels, e.g. (org.etsi.osl.*)</li> </ul>"},{"location":"service_design/kubernetes/ExposingKubernetesResources/#expose-crds-as-service-specifications-in-openslice-catalogs","title":"Expose CRDs as Service Specifications in OpenSlice catalogs","text":"<p>A CRD by default is exposed as a Resource Specification</p> <p>To ensure unique names across the clusters that OpenSlice can manage, the name of a CRD is constructed as follows:</p> <p><code>Kind @ ApiGroup/version @ ContextCluster @ masterURL</code></p> <p>For example you might see resource Specifications like:</p> <pre><code>- ```Application@argoproj.io/v1alpha1@kubernetes@https://10.10.10.144:6443/```\n- ```IPAddressPool@metallb.io/v1beta1@kubernetes@https://10.10.10.144:6443/```\n- ```Provider@pkg.crossplane.io/v1@kubernetes@https://10.10.10.144:6443/```\n</code></pre> <p>All attributes of the CRD are translated into characteristics</p> <p>The following specific characteristics are added:</p> <pre><code> - _CR_SPEC: Used for providing the json Custom Resource description to apply\n - _CR_CHECK_FIELD: Used for providing the field that need to be checked for the resource status\n - _CR_CHECKVAL_STANDBY: Used for providing the equivalent value from resource to signal the standby status\n - _CR_CHECKVAL_ALARM: Used for providing the equivalent value from resource to signal the alarm status\n - _CR_CHECKVAL_AVAILABLE: Used for providing the equivalent value from resource to signal the available status\n - _CR_CHECKVAL_RESERVED: Used for providing the equivalent value from resource to signal the reserved status\n - _CR_CHECKVAL_UNKNOWN: Used for providing the equivalent value from resource to signal the unknown status\n - _CR_CHECKVAL_SUSPENDED: Used for providing the equivalent value from resource to signal the suspended status\n</code></pre> <ol> <li> <p>Create a new Service Specification and use this Resource Specification in Resource Specification Relationships</p> <ul> <li>Then the Service Specification is saved as ResourceFacingServiceSpecification</li> </ul> <p>1.1. You can give at this stage values to the characteristics:</p> <pre><code>- _CR_SPEC, \n- _CR_CHECK_FIELD\n- _CR_CHECKVAL_STANDBY\n- _CR_CHECKVAL_ALARM\n- _CR_CHECKVAL_AVAILABLE\n- _CR_CHECKVAL_RESERVED\n- _CR_CHECKVAL_UNKNOWN\n- _CR_CHECKVAL_SUSPENDED\n</code></pre> <p>1.2. You can now create LCM rules if you wish</p> </li> <li> <p>Create a new Service Specification and use the Resource Facing Service Specification in Service Specification Relationships</p> <ul> <li>Then the Service Specification is saved as CustomerFacingServiceSpecification</li> </ul> <p>2.1. You can give at this stage values to the characteristics: </p> <pre><code>- _CR_SPEC, \n- _CR_CHECK_FIELD\n- _CR_CHECKVAL_STANDBY\n- _CR_CHECKVAL_ALARM\n- _CR_CHECKVAL_AVAILABLE\n- _CR_CHECKVAL_RESERVED\n- _CR_CHECKVAL_UNKNOWN\n- _CR_CHECKVAL_SUSPENDED\n</code></pre> <p>2.2. You We can create LCM rules for this new Service Specification</p> <p>2.3. You Expose configurable values for users to configure during service order</p> </li> </ol> <p></p>"},{"location":"service_design/kubernetes/ExposingKubernetesResources/#service-orchestration-and-crdscrs","title":"Service Orchestration and CRDs/CRs","text":"<p>OSOM - OpenSlice Service Orchestrator, checks the presence of attribute _CR_SPEC at the RFS to make a request for a CR deployment</p> <ul> <li>_CR_SPEC is a JSON or YAML string that is used for the request<ul> <li>It is similar to what one will do with e.g. a kubectl apply</li> <li>There are tools to translate a yaml file to a json</li> </ul> </li> </ul> <p>LCM rules can be used to change attributes of this yaml/json file, before sending this for orchestration</p>"},{"location":"service_design/kubernetes/ExposingKubernetesResources/#mapping-the-cr-lifecycle-that-is-defined-in-the-crd-with-the-openslice-tmf-based-resource-lifecycle","title":"Mapping the CR lifecycle that is defined in the CRD with the OpenSLice (TMF-based) resource Lifecycle","text":"<p>OpenSlice adds automatically as we see the following characteristics: </p> <pre><code> - _CR_CHECK_FIELD\n - _CR_CHECKVAL_STANDBY\n - _CR_CHECKVAL_ALARM\n - _CR_CHECKVAL_AVAILABLE\n - _CR_CHECKVAL_RESERVED\n - _CR_CHECKVAL_UNKNOWN\n - _CR_CHECKVAL_SUSPENDED\n</code></pre> <p>These characteristics instrument OpenSlice services to manage and reflect the lifecycle of a kubernetes resource to OpenSlice's (TMF based) lifecycle</p> <ul> <li>_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) </li> <li>_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) </li> <li>_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) </li> <li>_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) </li> <li>_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) </li> <li>_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) </li> <li>_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) </li> </ul>"},{"location":"service_design/kubernetes/ExposingKubernetesResources/#probe-further","title":"Probe further","text":"<ul> <li>See examples of exposing operators via OpenSlice:<ul> <li>Exposing Kubernetes Operators as a Service : Offering \"Calculator as a Service\" through OpenSlice</li> </ul> </li> <li>Learn more about CRIDGE, the service in OSL that manages CRDs/CRs</li> </ul>"},{"location":"service_design/kubernetes/helm/HELM_Installation_aaS_Jenkins_Example/","title":"Example: Offer Jenkins as a Service via Openslice","text":"<p>Before reading this example please make sure that you went through the Design Helm as a Service </p> <p>We will use the <code>Kind: Application</code> of ArgoCD and create a ResourceFacingServiceSpecification for Jenkins</p> <pre><code>1. Go to Service Specifications\n2. Create New Specification\n3. Give a Name, eg. jenkinsrfs\n4. Go to Resource Specification Relationships\n5. Assign ```Application@argoproj.io/v1alpha1@kubernetes@https://10.10.10.144:6443/```\n</code></pre> <p></p> <p>Focus now on the characteristics configuration.</p> <p>First we need to map the lifecycle of ArgoCD Application to TMF Resource State</p> <p></p> <p>In ArgoCD the field health.status has the value that we need to check (Healty, Progressing, etc)</p> <p>The _CR_SPEC can be designed first in a YAML or json editor. Let's see a YAML definition:</p> <p>```</p> <p>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: 4.6.1 chart: jenkins helm: values: | controller: service: type: ClusterIP syncPolicy: automated: prune: true selfHeal: true allowEmpty: false syncOptions: - Validate=false - CreateNamespace=true - PrunePropagationPolicy=foreground - PruneLast=true - RespectIgnoreDifferences=true ```</p> <p>NOTICE</p> <p>On each installation OSOM will change the name of the resource in order to be unique (will have a UUID)</p> <p><code>name: openslice-jenkins</code> </p> <p>destination namespace that ArgoCD will use is the name <code>opencrdtest</code></p> <p><code>destination: namespace: opencrdtest</code></p> <p>This implies that ArgoCD installs the Jenkins always in the same namespace</p> <p>To avoid this we will create a simple pre-provision rule to change the namespace properly</p> <p>See the following image: </p> <p></p> <ol> <li>Drag-Drop the _CR_SPEC characteristic of jenkinsrfs from the Service>Text blocks</li> <li>Drag-Drop Text>Formatted text block</li> <li>Drag-Drop Text>Multi-line text input block</li> <li>Copy paste the YAML text</li> <li>Change the spec: destination:namespace to the value %s</li> <li>Drag-Drop Lists>Create list with block delete 2 items (click the gear icon). Connect it to formatted text block</li> <li>Drag-Drop Context>Current Service Order block and select the id. Connect it to the List</li> <li>Save the PRE_PROVISION Rule</li> </ol>"},{"location":"service_design/kubernetes/helm/HELM_Installation_aaS_Jenkins_Example/#expose-the-service-to-your-users","title":"Expose the service to your users","text":"<p>Expose then as CustomerFacingServiceSpecification by using the previous RFSS as Service Specification Relationship 1. Create a Jenkins service and mark as Bundle and save it 2. Go to Service Specification Relationships and assign Jenkinsrfs 3. Add also a Logo if you wish</p> <p></p> <p></p> <p>Expose it now to a Category and a Catalog to be available for ordering.</p> <p></p>"},{"location":"service_design/kubernetes/helm/HELM_Installation_aaS_Jenkins_Example/#order-the-service","title":"Order the service","text":"<p>Order the service from the catalog. </p> <p>Soon the order will be completed and the Services will be active</p> <p></p>"},{"location":"service_design/kubernetes/helm/HELM_Installation_aaS_Jenkins_Example/#how-to-access-the-jenkins-installation","title":"How to access the Jenkins installation:","text":"<p>From the Supporting services of the Service Order, select the ResourceFacingService (jenkinsrfs)</p> <p>The ResourceFacingService has also supporting resources in resource inventory.</p> <p></p> <p>One is the resource reference to the application (e.g. cr_tmpname...), the other is a secret (e.g. cr87893...). </p> <p>Click to go to the secret resource (This is in the Resource inventory of OpenSlice)</p> <p></p> <p>Use them to login in your Jenkins.</p> <p>Exposing Jenkins to you external is a matter of cluster configuration and request (nodeport, load balancing, etc)! This is not a topic for this example</p>"},{"location":"service_design/kubernetes/helm/design_helmaas/","title":"Expose HELM charts as Service Specifications","text":"<p>Manage Helm charts installations via OpenSlice Service Specifications and Service Orders.</p>"},{"location":"service_design/kubernetes/helm/design_helmaas/#intended-audience-service-designers","title":"Intended Audience: Service Designers","text":"<p>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. </p> <p>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</p> <p>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:</p> <pre><code> - Reduces the complexity of deploying Microservices\n - Enhances deployment speed\n - Developers already know the technology\n</code></pre> <p>There are many Helm charts and Helm repositories there that are ready to be used</p> <p>Enable loose coupling and more orchestration scenarios</p> <p>Developers create and deploy applications in things they already know (e.g. Helm charts)</p> <p>Use the TMF models as wrapper entities around Helm charts</p> <p>Use OpenSlice to expose them in service catalogs and deploy them in complex scenarios (service bundles) involving also other systems:</p> <pre><code>- Include e.g. RAN controllers, \n- Pass values through life cycle rules from one service to another, \n- Manage multiple Helms in multiple clusters\n</code></pre>"},{"location":"service_design/kubernetes/helm/design_helmaas/#the-installation-of-helm-charts-is-based-on-openslice-crd-support","title":"The installation of HELM charts is based on OpenSlice CRD support","text":"<p>Please read more here</p> <p>For installing HELM charts we will use ArgoCD a well known Kubernetes-native continuous deployment (CD) tool </p> <p>ArgoCD is a Kubernetes-native continuous deployment (CD) tool</p> <p>While just deploying Heml charts is just a scenario for ArgoCD , in future one can exploit it for many things</p> <p>Despite some other tools like FluxCD, it provides also a UI which is useful for management and troubleshooting</p> <p>We will mainly use the CRD of <code>Kind: Application</code> that ArgoCD can manage</p> <p>Before proceeding, install ArgoCD in your management cluster, by following ArgoCD instructions</p> <p>As soon as you install ArgoCD, OpenSlice is automatically aware for specific new Kinds. The one we will use is is the <code>Kind: Application</code> that ArgoCD can manage under the apiGroup argoproj.io</p> <p>Browse to Resource Specifications. You will see an entry like the following:</p> <p><code>Application@argoproj.io/v1alpha1@kubernetes@https://10.10.10.144:6443/</code></p> <p>see image: </p> <p></p>"},{"location":"service_design/kubernetes/helm/design_helmaas/#whats-next","title":"What's next","text":"<p>See the Example: Offer Jenkins as a Service via Openslice </p>"},{"location":"service_design/lcmrules/examples/","title":"Examples of Rules","text":"<p>The following images provide some examples of rules.</p>"},{"location":"service_design/lcmrules/examples/#define-variables-according-to-cases","title":"Define variables according to cases","text":"<p>In the following example we :</p> <ul> <li>define a String variable. </li> <li>Then according to the Area of Service selected from the Service Order of the Service Specification we need to define it properly.</li> <li>We output the value to the OSOM Log</li> <li>Define dynamically the value of another parameter (This is fictional) and then do some other condition check</li> </ul> <p>The strAreaCodes could be passed then e.g. to NFVO for instantiation of services to these cells.</p> <p></p>"},{"location":"service_design/lcmrules/examples/#define-rules-to-create-a-resource-for-a-kubernetes-operator","title":"Define Rules to create a resource for a Kubernetes Operator","text":"<ul> <li>Modify the _CR_SPEC characteristic</li> <li>Add an \"Input with variables block\"</li> <li>Add a multiline Text block</li> <li>Mark with %s, %d, etc the parameters to modify with some action</li> <li>Add a list with the variables and their values</li> </ul> <p>in the example we modify a YAML spec with parama, paramb, action values from the characteristics spec.parama, spec.paramb, spec.action</p> <p></p>"},{"location":"service_design/lcmrules/examples/#define-complex-osm-configs-for-day-0","title":"Define complex OSM configs for DAY 0","text":"<p>The following displays some complex examples for defining the parameters to pass to the NFV. In this case is OSM.</p> <ul> <li> <p>NOTE: The OSM_CONFIG characteristic of a service is the one that it is used in orchestration to instantiate NS from OSM</p> </li> <li> <p>check the variable strTargetsParam. It is passed to the variable strOsmConfig3 which is executed if the Number of Cameras is more than 100. </p> </li> <li>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.</li> <li>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!)</li> <li>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</li> </ul> <p></p>"},{"location":"service_design/lcmrules/examples/#define-and-instantiate-different-services-according-to-service-order-request","title":"Define and instantiate different services according to Service Order request","text":"<p>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.</p> <p>There are different ways to accomplish this:</p> <ul> <li>create dynamically New Service Orders of RFSs with equivalent quality of Services</li> <li>change for example the VIMs that you deploy the NS</li> <li>change the NSD (that is use different VNFs)</li> </ul> <p>The following image displays for example the latter case.</p> <p></p>"},{"location":"service_design/lcmrules/examples/#call-an-external-restful-service","title":"Call an external RESTful service","text":"<p>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)</p> <p></p> <p></p>"},{"location":"service_design/lcmrules/examples/#create-new-service-orders","title":"Create New Service Orders","text":"<p>The following example calls to Order a New Service Specification with specific Parameter Values</p> <p></p>"},{"location":"service_design/lcmrules/intro/","title":"LCM Rules introduction","text":"<p>Lifecycle Management Rules: Defining complex conditions and actions during the lifecycle of a service and any necessary modifications throughout the service lifecycle.</p>"},{"location":"service_design/lcmrules/intro/#intended-audience-service-designers","title":"Intended Audience: Service Designers","text":"<p>In Naas LCM Introduction it was presented briefly the LCM Rules concept.</p> <p>This section goes deeply on how Service Designers can use them.</p> <p>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:</p> <ul> <li>PRE_PROVISION</li> <li>CREATION</li> <li>AFTER_ACTIVATION </li> <li>SUPERVISION </li> <li>AFTER_DEACTIVATION </li> </ul> <p>The following figure displays the different phases that the rules are performed, during the lifecycle of a Network Slice Instance.</p> <p></p> <ul> <li>PRE_PROVISION rules: Run only once just before creating a service with a given priority. </li> <li>CREATION rules: Run while the referenced service dependencies of a service are created</li> <li>AFTER_ACTIVATION rules: Run only once just after a service get the ACTIVE state</li> <li>SUPERVISION rules: Run when a characteristic of a service is changed and the service is in the ACTIVE state </li> <li>AFTER_DEACTIVATION rules: Run only once just after a service get the INACTIVE/TERMINATED state </li> </ul> <p>In general the rules allow to perform many actions during service LCM. Thes are some examples:</p> <ul> <li>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</li> <li>Translate GST/NEST parameter values to other values passed later to NFVO for instantiation or control</li> <li>Define complex OSM Configs based on other dependencies and passing variables</li> <li>Define any dependencies when creating the referenced services</li> <li>Dynamically include new service dependencies</li> <li>Create new service orders so include dynamically other services</li> <li>Call external (RESTful) services (via http(s), define payload, examine response)</li> </ul>"},{"location":"service_design/lcmrules/intro/#examine-if-the-rules-are-executed-successfully","title":"Examine if the rules are executed successfully","text":"<p>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.</p>"},{"location":"service_design/lcmrules/intro/#lcm-rules-and-osom-service-orchestration","title":"LCM Rules and OSOM Service Orchestration","text":"<p>OSOM is the responsible service for executing the rules on a specific phase. The following image explains the design in the BPMN phases:</p> <p></p>"},{"location":"service_design/lcmrules/intro/#define-rules","title":"Define rules","text":"<p>Rules are defined when designing a Service Spec. Here is an example of a list of rules:</p> <p></p> <p>Execution order of rules on a specific phase is random</p> <ul> <li>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.</li> </ul>"},{"location":"service_design/lcmrules/intro/#definition-language","title":"Definition language","text":"<ul> <li>The visual language that Openslice used is based on Google's Blockly (see https://developers.google.com/blockly)</li> <li>The blockly graph is automatically translated to Java internally and then dynamically executed during orchestration phases.</li> </ul> <p>The following figure is an example of such a rule design. The rule for example will run in PRE_PROVISION phase:</p> <p></p> <ul> <li>The goal of the above rule is to properly define a variable AreaCodes given the chosen AreaOfService from a Service Order.</li> <li>On the right side the user can define some rule properties or observe the underlying generated java code.</li> </ul>"},{"location":"service_design/lcmrules/intro/#the-blocks-library","title":"The blocks library","text":"<p>See our LCM Blocks specification</p>"},{"location":"service_design/lcmrules/intro/#examples-of-rules","title":"Examples of Rules","text":"<p>The following images provide some examples of rules.</p>"},{"location":"service_design/lcmrules/intro/#define-variables-according-to-cases","title":"define variables according to cases","text":"<p>In the following example we :</p> <ul> <li>define a String variable. </li> <li>Then according to the Area of Service selected from the Service Order of the Service Specification we need to define it properly.</li> <li>We output the value to the OSOM Log</li> <li>Define dynamically the value of another parameter (This is fictional) and then do some other condition check</li> </ul> <p>The strAreaCodes could be passed then e.g. to NFVO for instantiation of services to these cells.</p> <p></p>"},{"location":"service_design/lcmrules/intro/#define-complex-osm-configs-for-day-0","title":"Define complex OSM configs for DAY 0","text":"<p>The following displays some complex examples for defining the parameters to pass to the NFV. In this case is OSM.</p> <ul> <li> <p>NOTE: The OSM_CONFIG characteristic of a service is the one that it is used in orchestration to instantiate NS from OSM</p> </li> <li> <p>check the variable strTargetsParam. It is passed to the variable strOsmConfig3 which is executed if the Number of Cameras is more than 100. </p> </li> <li>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.</li> <li>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!)</li> <li>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</li> </ul> <p></p>"},{"location":"service_design/lcmrules/intro/#define-and-instantiate-different-services-according-to-service-order-request","title":"Define and instantiate different services according to Service Order request","text":"<p>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.</p> <p>There are different ways to accomplish this:</p> <ul> <li>create dynamically New Service Orders of RFSs with equivalent quality of Services</li> <li>change for example the VIMs that you deploy the NS</li> <li>change the NSD (that is use different VNFs)</li> </ul> <p>The following image displays for example the latter case.</p> <p></p>"},{"location":"service_design/lcmrules/intro/#call-an-external-restful-service","title":"Call an external RESTful service","text":"<p>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)</p> <p></p> <p></p>"},{"location":"service_design/lcmrules/intro/#create-new-service-orders","title":"Create New Service Orders","text":"<p>The following example calls to Order a New Service Specification with specific Parameter Values</p> <p></p>"},{"location":"service_design/lcmrules/intro/#probe-further","title":"Probe further","text":"<ul> <li>Check our examples for more usages</li> <li>See next the complete specification</li> </ul>"},{"location":"service_design/lcmrules/specification/","title":"LCM Blocks specification","text":""},{"location":"service_design/lcmrules/specification/#intended-audience-service-designers","title":"Intended Audience: Service Designers","text":"<p>The following images describe some blocks found in the library.</p> <p>Blockly has syntax rules. It helps with colours to define them. </p> <p>So for example a parameter that is a Number cannot be \"glued\" with a String. Will need some conversion first</p> <p> </p>"},{"location":"service_ordering/ordering_services/","title":"Service Ordering","text":""},{"location":"service_ordering/ordering_services/#intended-audience-users","title":"Intended Audience: Users","text":""}]}
\ No newline at end of file
diff --git a/public/develop/service_design/lcmrules/examples/index.html b/public/develop/service_design/lcmrules/examples/index.html
index dff569ad..1a62170a 100644
--- a/public/develop/service_design/lcmrules/examples/index.html
+++ b/public/develop/service_design/lcmrules/examples/index.html
@@ -75,6 +75,11 @@
<label class="md-overlay" for="__drawer"></label>
<div data-md-component="skip">
+
+ <a href="#examples-of-rules" class="md-skip">
+ Skip to content
+ </a>
+
</div>
<div data-md-component="announce">
@@ -1661,6 +1666,19 @@
<input class="md-nav__toggle md-toggle" type="checkbox" id="__toc">
+
+
+
+ <label class="md-nav__link md-nav__link--active" for="__toc">
+
+
+ <span class="md-ellipsis">
+ Typical Examples
+ </span>
+
+
+ <span class="md-nav__icon md-icon"></span>
+ </label>
<a href="./" class="md-nav__link md-nav__link--active">
@@ -1672,6 +1690,79 @@
</a>
+
+
+<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
+
+
+
+
+
+
+ <label class="md-nav__title" for="__toc">
+ <span class="md-nav__icon md-icon"></span>
+ Table of contents
+ </label>
+ <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
+
+ <li class="md-nav__item">
+ <a href="#define-variables-according-to-cases" class="md-nav__link">
+ <span class="md-ellipsis">
+ Define variables according to cases
+ </span>
+ </a>
+
+</li>
+
+ <li class="md-nav__item">
+ <a href="#define-rules-to-create-a-resource-for-a-kubernetes-operator" class="md-nav__link">
+ <span class="md-ellipsis">
+ Define Rules to create a resource for a Kubernetes Operator
+ </span>
+ </a>
+
+</li>
+
+ <li class="md-nav__item">
+ <a href="#define-complex-osm-configs-for-day-0" class="md-nav__link">
+ <span class="md-ellipsis">
+ Define complex OSM configs for DAY 0
+ </span>
+ </a>
+
+</li>
+
+ <li class="md-nav__item">
+ <a href="#define-and-instantiate-different-services-according-to-service-order-request" class="md-nav__link">
+ <span class="md-ellipsis">
+ Define and instantiate different services according to Service Order request
+ </span>
+ </a>
+
+</li>
+
+ <li class="md-nav__item">
+ <a href="#call-an-external-restful-service" class="md-nav__link">
+ <span class="md-ellipsis">
+ Call an external RESTful service
+ </span>
+ </a>
+
+</li>
+
+ <li class="md-nav__item">
+ <a href="#create-new-service-orders" class="md-nav__link">
+ <span class="md-ellipsis">
+ Create New Service Orders
+ </span>
+ </a>
+
+</li>
+
+ </ul>
+
+</nav>
+
</li>
@@ -2635,6 +2726,70 @@
+
+
+
+ <label class="md-nav__title" for="__toc">
+ <span class="md-nav__icon md-icon"></span>
+ Table of contents
+ </label>
+ <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
+
+ <li class="md-nav__item">
+ <a href="#define-variables-according-to-cases" class="md-nav__link">
+ <span class="md-ellipsis">
+ Define variables according to cases
+ </span>
+ </a>
+
+</li>
+
+ <li class="md-nav__item">
+ <a href="#define-rules-to-create-a-resource-for-a-kubernetes-operator" class="md-nav__link">
+ <span class="md-ellipsis">
+ Define Rules to create a resource for a Kubernetes Operator
+ </span>
+ </a>
+
+</li>
+
+ <li class="md-nav__item">
+ <a href="#define-complex-osm-configs-for-day-0" class="md-nav__link">
+ <span class="md-ellipsis">
+ Define complex OSM configs for DAY 0
+ </span>
+ </a>
+
+</li>
+
+ <li class="md-nav__item">
+ <a href="#define-and-instantiate-different-services-according-to-service-order-request" class="md-nav__link">
+ <span class="md-ellipsis">
+ Define and instantiate different services according to Service Order request
+ </span>
+ </a>
+
+</li>
+
+ <li class="md-nav__item">
+ <a href="#call-an-external-restful-service" class="md-nav__link">
+ <span class="md-ellipsis">
+ Call an external RESTful service
+ </span>
+ </a>
+
+</li>
+
+ <li class="md-nav__item">
+ <a href="#create-new-service-orders" class="md-nav__link">
+ <span class="md-ellipsis">
+ Create New Service Orders
+ </span>
+ </a>
+
+</li>
+
+ </ul>
</nav>
</div>
@@ -2649,9 +2804,59 @@
- <h1>Typical Examples</h1>
-
-
+<h1 id="examples-of-rules">Examples of Rules</h1>
+<p>The following images provide some examples of rules.</p>
+<h3 id="define-variables-according-to-cases">Define variables according to cases</h3>
+<p>In the following example we :</p>
+<ul>
+<li>define a String variable. </li>
+<li>Then according to the Area of Service selected from the Service Order of the Service Specification we need to define it properly.</li>
+<li>We output the value to the OSOM Log</li>
+<li>Define dynamically the value of another parameter (This is fictional) and then do some other condition check</li>
+</ul>
+<p>The strAreaCodes could be passed then e.g. to NFVO for instantiation of services to these cells.</p>
+<p><a href="../images/lcm/lcmfig9.png"><img alt="lcmrules" src="../images/lcm/lcmfig9.png" /></a></p>
+<h3 id="define-rules-to-create-a-resource-for-a-kubernetes-operator">Define Rules to create a resource for a Kubernetes Operator</h3>
+<ul>
+<li>Modify the _CR_SPEC characteristic</li>
+<li>Add an "Input with variables block"</li>
+<li>Add a multiline Text block</li>
+<li>Mark with %s, %d, etc the parameters to modify with some action</li>
+<li>Add a list with the variables and their values</li>
+</ul>
+<p>in the example we modify a YAML spec with parama, paramb, action values from the characteristics spec.parama, spec.paramb, spec.action</p>
+<p><a href="../images/lcm/lcmfig15.png"><img alt="lcmrules" src="../images/lcm/lcmfig15.png" /></a></p>
+<h3 id="define-complex-osm-configs-for-day-0">Define complex OSM configs for DAY 0</h3>
+<p>The following displays some complex examples for defining the parameters to pass to the NFV. In this case is OSM.</p>
+<ul>
+<li>
+<p>NOTE: The OSM_CONFIG characteristic of a service is the one that it is used in orchestration to instantiate NS from OSM</p>
+</li>
+<li>
+<p>check the variable strTargetsParam. It is passed to the variable strOsmConfig3 which is executed if the Number of Cameras is more than 100. </p>
+</li>
+<li>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.</li>
+<li>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!)</li>
+<li>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</li>
+</ul>
+<p><a href="../images/lcm/lcmfig10.png"><img alt="lcmrules" src="../images/lcm/lcmfig10.png" /></a></p>
+<h3 id="define-and-instantiate-different-services-according-to-service-order-request">Define and instantiate different services according to Service Order request</h3>
+<p>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.</p>
+<p>There are different ways to accomplish this:</p>
+<ul>
+<li>create dynamically New Service Orders of RFSs with equivalent quality of Services</li>
+<li>change for example the VIMs that you deploy the NS</li>
+<li>change the NSD (that is use different VNFs)</li>
+</ul>
+<p>The following image displays for example the latter case.</p>
+<p><a href="../images/lcm/lcmfig11.png"><img alt="lcmrules" src="../images/lcm/lcmfig11.png" /></a></p>
+<h3 id="call-an-external-restful-service">Call an external RESTful service</h3>
+<p>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)</p>
+<p><a href="../images/lcm/lcmfig12.png"><img alt="lcmrules" src="../images/lcm/lcmfig12.png" /></a></p>
+<p><a href="../images/lcm/lcmfig13.png"><img alt="lcmrules" src="../images/lcm/lcmfig13.png" /></a></p>
+<h3 id="create-new-service-orders">Create New Service Orders</h3>
+<p>The following example calls to Order a New Service Specification with specific Parameter Values</p>
+<p><a href="../images/lcm/lcmfig14.png"><img alt="lcmrules" src="../images/lcm/lcmfig14.png" /></a></p>
diff --git a/public/develop/service_design/lcmrules/images/lcm/lcmfig15.png b/public/develop/service_design/lcmrules/images/lcm/lcmfig15.png
new file mode 100644
index 0000000000000000000000000000000000000000..0005c110adce2a14ba143ee54b46e948d4f81c19
GIT binary patch
literal 292068
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
XHh0+kyMXHr^d%#qC|)jV?EilN#Re(+
literal 0
HcmV?d00001
diff --git a/public/develop/service_design/lcmrules/intro/index.html b/public/develop/service_design/lcmrules/intro/index.html
index fa06d35a..03f83836 100644
--- a/public/develop/service_design/lcmrules/intro/index.html
+++ b/public/develop/service_design/lcmrules/intro/index.html
@@ -3010,14 +3010,7 @@
<li>On the right side the user can define some rule properties or observe the underlying generated java code.</li>
</ul>
<h2 id="the-blocks-library">The blocks library</h2>
-<p>The following images describe some blocks found in the library.</p>
-<p>Blockly has syntax rules. It helps with colours to define them. </p>
-<p>So for example a parameter that is a Number cannot be "glued" with a String. Will need some conversion first</p>
-<p><a href="../images/lcm/lcmfig4.png"><img alt="lcmrules" src="../images/lcm/lcmfig4.png" /></a>
-<a href="../images/lcm/lcmfig5.png"><img alt="lcmrules" src="../images/lcm/lcmfig5.png" /></a>
-<a href="../images/lcm/lcmfig6.png"><img alt="lcmrules" src="../images/lcm/lcmfig6.png" /></a>
-<a href="../images/lcm/lcmfig7.png"><img alt="lcmrules" src="../images/lcm/lcmfig7.png" /></a>
-<a href="../images/lcm/lcmfig8.png"><img alt="lcmrules" src="../images/lcm/lcmfig8.png" /></a></p>
+<p>See our <a href="../specification/">LCM Blocks specification</a></p>
<h2 id="examples-of-rules">Examples of Rules</h2>
<p>The following images provide some examples of rules.</p>
<h3 id="define-variables-according-to-cases">define variables according to cases</h3>
diff --git a/public/develop/service_design/lcmrules/specification/index.html b/public/develop/service_design/lcmrules/specification/index.html
index ba5318e6..d8283950 100644
--- a/public/develop/service_design/lcmrules/specification/index.html
+++ b/public/develop/service_design/lcmrules/specification/index.html
@@ -75,6 +75,11 @@
<label class="md-overlay" for="__drawer"></label>
<div data-md-component="skip">
+
+ <a href="#lcm-blocks-specification" class="md-skip">
+ Skip to content
+ </a>
+
</div>
<div data-md-component="announce">
@@ -1640,6 +1645,19 @@
<input class="md-nav__toggle md-toggle" type="checkbox" id="__toc">
+
+
+
+ <label class="md-nav__link md-nav__link--active" for="__toc">
+
+
+ <span class="md-ellipsis">
+ Specification
+ </span>
+
+
+ <span class="md-nav__icon md-icon"></span>
+ </label>
<a href="./" class="md-nav__link md-nav__link--active">
@@ -1651,6 +1669,34 @@
</a>
+
+
+<nav class="md-nav md-nav--secondary" aria-label="Table of contents">
+
+
+
+
+
+
+ <label class="md-nav__title" for="__toc">
+ <span class="md-nav__icon md-icon"></span>
+ Table of contents
+ </label>
+ <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
+
+ <li class="md-nav__item">
+ <a href="#intended-audience-service-designers" class="md-nav__link">
+ <span class="md-ellipsis">
+ Intended Audience: Service Designers
+ </span>
+ </a>
+
+</li>
+
+ </ul>
+
+</nav>
+
</li>
@@ -2635,6 +2681,25 @@
+
+
+
+ <label class="md-nav__title" for="__toc">
+ <span class="md-nav__icon md-icon"></span>
+ Table of contents
+ </label>
+ <ul class="md-nav__list" data-md-component="toc" data-md-scrollfix>
+
+ <li class="md-nav__item">
+ <a href="#intended-audience-service-designers" class="md-nav__link">
+ <span class="md-ellipsis">
+ Intended Audience: Service Designers
+ </span>
+ </a>
+
+</li>
+
+ </ul>
</nav>
</div>
@@ -2649,9 +2714,16 @@
- <h1>Specification</h1>
-
-
+<h1 id="lcm-blocks-specification">LCM Blocks specification</h1>
+<h2 id="intended-audience-service-designers">Intended Audience: Service Designers</h2>
+<p>The following images describe some blocks found in the library.</p>
+<p>Blockly has syntax rules. It helps with colours to define them. </p>
+<p>So for example a parameter that is a Number cannot be "glued" with a String. Will need some conversion first</p>
+<p><a href="../images/lcm/lcmfig4.png"><img alt="lcmrules" src="../images/lcm/lcmfig4.png" /></a>
+<a href="../images/lcm/lcmfig5.png"><img alt="lcmrules" src="../images/lcm/lcmfig5.png" /></a>
+<a href="../images/lcm/lcmfig6.png"><img alt="lcmrules" src="../images/lcm/lcmfig6.png" /></a>
+<a href="../images/lcm/lcmfig7.png"><img alt="lcmrules" src="../images/lcm/lcmfig7.png" /></a>
+<a href="../images/lcm/lcmfig8.png"><img alt="lcmrules" src="../images/lcm/lcmfig8.png" /></a></p>
--
GitLab