Context Broker

Introduction

Orion-LD is an open-source implementation of the NGSI-LD context broker developed by the FIWARE Foundation, which is continuously being improved within the scope of aerOS. This broker plays a crucial role in the Data fabric of T4.2 and domain federation of T4.6, but for management reasons it has been decided to include this documentation under the data group.

Features

Context Brokers (CB) manage contextual information modelled as entities by storing the most recent values of their attributes. These values can be obtained through a direct HTTP request to a REST API or via a publish/subscribe mechanism provided by the CB.

Orion-LD i the NGSI-LD standard (the latest version is the 1.7.1 published in March 2024), which is an extended subset of JSON-LD for use with context management systems. In addition, it is developed in C, which is translated into a higher execution performance because this language is compiled rather than interpreted.

The context of each CB has a local scope as it is attached to the broker. Nevertheless, NGSI-LD provides mechanisms for distributing this local context information among different Context Brokers based on the creation of Context Source Registrations (CSR). A registration is a mechanism to inform an NGSI-LD CB about where to find more (non-local) entities. Upon queries, not only is an entity looked up in the local store of a broker, but the registrations are also consulted and for all matching registrations (e.g. a query to retrieve all entities of a certain type and the CB has a registration indicating that entities of that type can be found in another broker), a distributed query is sent to the broker behind the registration, and its information (its entities) is appended to the final response, so the process is completely transparent for the end user.

Finally, this spreadsheet describes the implementation status of Orion-LD.

Place in architecture

The Orion-LD context broker is key component in the aerOS architecture. For more details, please check the architecture of both aerOS Federator and Data Fabric components.

User guide

This is a list of useful official information about NGSI-LD and Orion-LD:

• Introduction to NGSI-LD Entities and Attributes

• A guide to the NGSI-LD Context

• Orion-LD quick start guide

• NGSI-LD tutorial step-by-step

• NGSI-LD in a Nutshell

• Examples of NGSI-LD payloads

• OpenAPI Specification for NGSI-LD API

Installation

The official container image is available in DockerHub and the latest release version is 1.6.0. In addition, a new image is automatically generated and uploaded for each push to the main branch (develop), although it’s not a new version release, just a development release.

However, as the testing and improvement of Orion-LD inside the scope of aerOS is constant, verified and tested changes in the source code are packaged into custom container images without waiting for official releases in Dockerhub. Therefore, these custom images are available in the Common deployments repository, under the name registry.gitlab.aeros-project.eu/aeros-public/common-deployments/orion-ld. The latest tag is 1.1.1 , which includes new features such as distributed subscriptions and advanced CSRs filtering.

Kubernetes

Install the aerOS custom Helm chart setting, at least, the DomainID parameter. All the described configurations can be customized using the aerOS Helm chart values:

helm install orion-ld aeros-common/orion-ld --set broker.args.brokerId=<DomainID> --set broker.service.ports.api.nodePort=31550 --set broker.args.traceLevel="70-99" --set subordinateEndpoint=<full-broker-url-pointing-to-/ex/v1-endpoint>

Docker

In Docker machines, get the docker-compose.yaml file and then edit it to set, at least, the DomainID parameter:

wget --header "PRIVATE-TOKEN: <token>" https://gitlab.aeros-project.eu/api/v4/projects/65/packages/generic/orion-ld/1.0.0/docker-compose.yaml

Configuration

Warning

• The use of the new MongoDB driver (-mongocOnly) must be enabled to use newer versions of MongoDB than the 6.0.

• A unique Broker ID must be set to ensure the proper functioning of the CSR and thus the aerOS Domain Federation.

Some CLI arguments must be included when running Orion-LD to be compliant with the aerOS requirements:

• -brokerId <broker_ID>: unique identifier for the context broker. This value must be the domain name in aerOS, for instance, CFDomain.

• -forwarding: enables brokers federation to perform distributed operations.

• -experimental: enables certain needed features.

• -wip [feature1,feature2,…,featureN]: enables new (under development) features. In aerOS it is recommended to use -wip entityMaps,distSubs.

  • entityMaps: CRUD operations for distributed NGSI-LD entities.

  • distSubs: distributed NGSI-LD subscriptions.

• -noArrayReduction: avoids the replacement of object arrays of a single element with an object. This happens by default because of JSON-LD specification.

• -subordinateEndpoint: only if the wip distSubs is enabled. It specifies the endpoint (e.g. https://domain.aeros-project.eu/orionld/ex/v1 or http://192.168.1.202:1028/ngsi-ld/ex/v1 that will be used to fill in the notification value of the subordinated subscriptions that are automatically created when a federated subscription is created.

Other CLI arguments for general purposes:

• -dbhost <mongodb_url>: url of the MongoDB database (e.g. 192.168.1.202:1028). The default value is localhost:1026.

• -t: trace levels. Use 0-255 to display all the information and 70-99 to display information about distributed operations.

• -logLevel <level>: log level, DEBUG is recommended.

• -disableFileLog: disables the storage of logging messages into the default /tmp/orionld.log file.

• -mongocOnly: enables the use of the new MongoDB driver for the C language, which provides a performance improvement. If it’s not included, the broker will use the legacy MongoDB driver (in C++) that only supports MongoDB versions older than the 6.0.

• -multiservice: enables multi tenancy mode, which means the use of NGSILD-Tenant header.

• -pageSize: page size for results pagination. The default value is 20, but it can be modified in runtime using the limit URL parameter in the queries.

• -socketService: enables a TCP socket that can be used for health checks. By default, it listens at 1027 TCP port.

• -ssPort <port_number>: modifies the TCP socket port (by default is 1027).

NGSI-LD entities persistence:

• -troe: enables the TRoE (temporal representation of entities) to persist the values of the entities attributes. It needs an additional Timescale database to work properly.

• -troeHost <postgresql_host>: host of the PostgreSQL database. The default value is localhost.

• -troePort <postgresql_port>: port of the PostgreSQL database. The default value is 5432.

• -troeUser <postgresql_user>: username of the PostgreSQL database. The default value is localhost.

• -troePwd <postgresql_pwd>: password of the PostgreSQL database. The default value is localhost.

Developer guide

The source code of Orion-LD is hosted in a GitHub repository under a AGPL-3.0 license. This repository also includes a developer guide, a local installation guide from source (it’s recommended to install Orion-LD from source in a machine with Ubuntu 20.04.1) and a guide for installing and using Functional Tests.

GitHub issues

The testing and improvement process of Orion-LD in aerOS has been conducted using GitHub issues, so this is the list of the issues opened in the scope of aerOS:

• #1466

• #1467

• #1468

• #1469

• #1478

• #1479

• #1480

• #1525

• #1551

• #1556

• #1583

• #1589

• #1630

• #1644

• #1652

• #1672

• #1673

• #1688

• #1692

• #1715

In addition, this is the list of Pull Requests without directly linked issues:

• #1596

• #1601

• #1640

• #1660

• #1661

• #1662

• #1718

Authors

Fiware Foundation (Orion-LD software) and Universitat Politènica de València (this documentation).

License

AGPL-3.0 license