The DOME Access-Node is a set of services for the integration with the DOME Marketplace. A registered participant can use it to act as a federated marketplace in DOME.
The DOME Access-Node consists of multiple open-source components. The components are not required to be used, as long as alternatives providing the same interfaces are used.
The Access-Nodes consists of 3 logical building blocks:
An implementation of the TMForum APIs. The TMForum serves as the main API for Marketplace implementations to interact with.
The TM-Forum-API Service is a service providing a growing subset of the TMForum API's while using an NGSI-LD context broker as persistence backend and change notificator.
The Context Broker serves as the (Off-Chain) Storage Backend for the TMForum-APIs and as a connection mechanism between different Access-Nodes to retrieve the actual data. It's recommended to use the Scorpio Context Broker.
The provided Access-Node Chart supports the usage of Scorpio in a resource-friendly installation (therefore without Kafka). For most installations, this should be powerful enough. In case of additional needs, please check the official Scorpio Documentation.
💡 The Scorpio installation uses PostgreSQL with the PostGIS as storage backend.
The Blockchain Connector is a software component that facilitates the interaction between the Off-Chain Storage (Context Broker) and the On-Chain Storage (Blockchain). It is composed of the Distributed Ledger Technology (DLT) and the Replication Service. Components:
- Blockchain-Connector (Replication Service):
- listens for changes events from the local broker and the DLT-Adapter (subscription)
- receives events from the local broker and the DLT-Adapter
- generates the blockchain events and writes them to the DLT-Adapter
- resolves blockchain events and retrieves the actual entities from their source, writes them to the Context Broker
- writes entities from the Blockchain-Connector to the local broker
- audit any transaction processed by the Blockchain-Connector and writes them to the local database.
- synchronizes data with the entities with the genesis node or the selected nodes
- DLT-Adapter:
- listens for DOME Events and notifies the Blockchain-Connector
- writes transactions with events received from the Blockchain-Connector to the blockchain
- retrieves transactions from the blockchain using a range of time parameter, and notifies the Blockchain-Connector
There are no known alternatives to the components at the moment.
💡 The Blockchain-Connector uses PostgreSQL as a storage backend. It can be replaced with any compatible alternative. While its possible to reuse the same instance as the broker, it's recommended to separate concerns and use 2 different instances.
💡 For detailed information on how to integrate with the DOME Marketplace, check the Integration Guide
It's recommended to install the Access-Node on Kubernetes(> 1.26.7), using Helm. For alternative installations, see the individual components' documentation.
💡 An example of a federated marketplace, deployed on top of a managed Kubernetes by IONOS can be found in DOME-Gitops
The Access-Node is provided as an Umbrella Chart, containing dependencies to all mentioned components, allowing to install them all at once:
helm repo add dome-access-node https://dome-marketplace.github.io/access-node
helm install <RELEASE_NAME> dome-access-node/access-node💡 All releases of the Access-Node reside in the helm-repository https://dome-marketplace.github.io/access-node.
It provides a sane set of default-values. To actually use the Access-Node the following values have to be replaced:
The TM-Forum-API service is a cluster of individual services providing one specific API each, enabling the participant to only run the necessary subset for its use-case. Apart from offering CRUD operations on the managed entities, the service also enables the subscription to notifications based on given queries.
The services are stateless and support horizontal scaling, but require an external cache to avoid having inconsistent caches. Inconsistent caches can result from either changes due to calls to the API, or due to notifications for changes reported by the underlying persistence. If run in a single instance mode, a local cache is acceptable but for larger setups a Redis installation is recommended.
For reasons of convenience, the TM-Forum-API service can be deploying with an Envoy API proxy which provides the individual APIs via a single service, routed based on the path. Another convenient feature is a RapiDoc container, that can be deployed with the TM-Forum-API service that provides an Openapi based API documentation for the deployed services, with the functionality of querying the API too.
The requirement for the persistence is to be compliant to the NGSI-LD API v1.6 enabling the use of different available context brokers. The currently recommended Context-Broker for the access node is Scorpio, mainly due to good cloud integration and overall support. The Scorpio context-broker allows a variety of adjustments to cover the operator's specific needs ( e.g. horizontal scaling utilizing Kafka) and uses Postgresql as it's persistence layer. The Postgresql is extended with PostGIS for supporting geospatial data.
The base memory consumption per deployed pod is listed below but is will increase with the amount of traffic, therefor should only be used as a rough estimate.
| Service | Memory (Mi) |
|---|---|
| TM Forum API | 250 |
| NGSI-LD Context Broker (Scorpio) | 400 |
| Persistence Layer (Postgres/PostGIS) | 150 |
| External Cache (Redis) | 10 |
| ... |
The recommended and endorsed way of deployment is via the provided Helm Chart (optionally wrapped in ArgoCD Applications).
To deploy the Access Node, an Umbrella Helm Chart can be used as followed.
Caution
Remember to securely store your private keys since it can't be recovered if lost. Avoid sharing or saving it in insecure places, as losing it may mean losing access to important resources. Consider using a secure password manager or a dedicated secrets vault to keep it safe.
-
Go to the DOME Key Generator:
-
Click the two buttons to generate the keys:
-
Register as a valid organization in the Trusted Access Node List of the corresponding environment following the instructions in the DOME Trust Framework.
💡 With the following tables you can relate the key names in the Dome Key Generator with the key names in the Trusted Access Node List:
Trusted Access Node List DOME Key Generator publicKey Desmos keys -> Public Key dlt_address DLT keys -> DLT Address -
Copy the private keys to your Access Node Helm Chart implementation and update the specified fields in How to configure section. You have a specific explanation about what you need to add in the Trusted Access Node List in: https://github.com/DOME-Marketplace/trust-framework#which-data-is-needed-to-set-a-new-entry-into-the-trusted-access-node-operators-list.
💡 With the following tables you can relate the key names in the Dome Key Generator with the key names in the Trusted Access Node List and the Access Node Helm Chart:
Access Node Helm Chart DOME Key Generator desmos.app.privateKey Desmos keys -> Private Key desmos.app.operator.organizationIdentifier Desmos keys -> DID dlt-adapter.env.PRIVATE_KEY DLT keys -> Private Key dlt-adapter.env.ISS DLT keys -> ISS -
Add the DOME Helm Chart Repository to your helm installation
helm repo add dome-access-node https://dome-marketplace.github.io/access-node helm repo update💡 All releases of the Access-Node reside in the helm-repository https://dome-marketplace.github.io/access-node. In addition to that, all Pre-Release versions(build from the Pull Requests) are provided in the pre-repo https://dome-marketplace.github.io/access-node/pre. The pre-repo will be cleaned-up from time to time, in order to keep the index manageable.
-
Install the DOME Access Node
helm install access-node dome-access-node/access-node --namespace <NAMESPACE> -f config/accessnode.yamlNAMESPACE: The Kubernetes Cluster namespace where the DOME Access Node will be deployed.
The chart is released with a set of default values which act as a good starting point for an adoption. These values are also documented, enhancing the understanding. Additionally, the of the components should be consulted.
To start, use this which includes only the settings likely to need adjustment by integrators.
-
Required Fields with Fixed Values
The following fields should be configured as specified, as they must always have the same values:
Key Description Value access-node.desmos.image.repository Repository of the image to deploy in2workspace/in2-desmos-api access-node.desmos.image.tag Image version v1.0.0 access-node.dlt-adapter.env.RPC_ADDRESS node address https://red-t.alastria.io/v0/9461d9f4292b41230527d57ee90652a6 -
Required Fields Generated by the DOME Key Generator
The following fields are specific to each integrator and should be generated via the DOME Key Generator:
Key Description Explanation access-node.desmos.app.operator.organizationIdentifier DID of the operator The "DID" key generated in the "Desmos keys" part DOME Key Generator access-node.desmos.app.privateKey Private key to sign JWT The "Private Key" generated in the "Desmos keys" part DOME Key Generator access-node.dlt-adapter.env.PRIVATE_KEY Private key for transaction signing The "Private Key" generated in the "DLT keys" part DOME Key Generator access-node.dlt-adapter.env.ISS Organization ID hashed with SHA-256 The "ISS" generated in the "DLT keys" part DOME Key Generator -
Custom Required Fields
These additional fields must also be specified by integrators:
Key Description Explanation access-node.desmos.app.profile allows the environment filtering dev/test/prod (see the desmos profile table below) access-node.desmos.app.broker.externalDomain must be set since it is used by third parties to retrieve your data; it should be https The external domain you're using to expose Desmos The Blockchain Connector uses the dev, test and prod configuration profiles. On the other hand, DOME uses the profile names sbx, dev and prd. It is important that users use the profile names used by the Blockchain Connector (dev, test, prod), since the application is responsible for carrying out the necessary correspondence and mapping between the profile names of the Blockchain Connector and those of DOME automatically.
desmos-api profiles DOME-Gitops environments dev sbx test dev prod prd
Fields to clarify in the original config:
| Key | Comment | Default Values |
|---|---|---|
| access-node.desmos.app.ngsiSubscription.entityTypes | this list ensures that you can work with all type of entities | catalog,product-offering,category,individual,organization,product,service-specification,product-offering-price,resource-specification,product-specification |
| access-node.desmos.app.txSubscription.entityTypes | this list ensures that you can work with all type of entities | catalog,product-offering,category,individual,organization,product,service-specification,product-offering-price,resource-specification,product-specification |
While secrets can be configured via plain helm/k8s entities, another more secure approach is to use Sealed Secrets. To configure custom secrets you have to follow the next steps:
-
Create a Plain Secret Manifest File:
- Create a plain secret manifest file named
<secret name>-plain-secret.yaml. - IMPORTANT: Add "*-plain-secret.yaml" to .gitignore file to not push plain secret data to the repository.
apiVersion: v1 kind: Secret metadata: name: <secret name> namespace: <app namespace> data: <secret_key>: <base64 encoded value>
- Create a plain secret manifest file named
-
Seal the secret:
- Seal the secret by executing the following command and add it to a "templates" folder:
kubeseal -f <secret name>-plain-secret.yaml -w <secret name>-sealed-secret.yaml --controller-namespace sealed-secrets --controller-name sealed-secrets
-
Update the Chart Values:
- In the chart values.yaml file, modify the existingSecret section as follows:
existingSecret: enabled: true name: <secret name> key: <secret_key>
All components are configured with health and readiness checks to validate their own status, therefor being the base for a validation. These checks are utilized in the kubernetes checks as defined in the helm charts.
TODO: Include RapiDoc Container for validation and add explanation here
- Management/admin APIs.
- Instrumentation, metrics, logs, alerts
The underlying database service holds the persisted data and therefor requires a backup&recovery mechanism when operated in a production environment. The use of managed database is strongly encouraged for safety and convenience.
The TM-Forum-API service used a json based log output by default, which can be parsed easily by log aggregators but can also be replaced if needed. The verbosity is controlled via environment variables and can be fine-tuned to the operators needs.
We need to implement Grafana dashboards but for the moment the access node publishes metrics for Prometheus by default in "/actuator/prometheus".
Upgrade to both a different chart version and new configuration can be accomplished with the following command
helm upgrade <RELEASE_NAME> dome-access-node/access-node --namespace <NAME_SPACE> --version <CHART_VERSION> -f values.yaml
Versioning of the main access-node helm chart is handled based on the labels used in the pull requests used to introduce changes and is enforced in the build pipeline. The requester and reviewers must set the label according to the SemVer 2.0.0 versioning scheme.
Versioning of the components and sub-charts is recommended to use the same scheme.
Versioning, release notes, stability considerations
To be filled once feedback from integrators comes in
When encountering timeouts in calls to the TM-Forum-API service it is possible to mitigate the imminent issue by increasing the timeout of the client (called "ngsi") calling the NGSI-LD broker. The necessary client and server configuration can be handed in via additional environment variables.
The Helm-Chart is integration-tested with a local k3s-instance.
The test uses the following tools:
- templated by Helm, using the Helm Maven-Plugin
- deployed with the k3s Maven-Plugin
- tested with Cucumber
The test-setup looks as following:
The TMForum-APIs are mapped to local ports:
- provider: localhost:8080
- consumer: localhost:8081
To execute all tests, run:
mvn clean integration-testThe definition of features is available under the test-resources. Steps can be added to the StepDefinitions or through a new class. Rest-Clients to all TMForum-APIs are generated and can be used inside the tests:
var serviceCatalogApiProvider = new ServiceCatalogApi();
// base address of the local provider tmforum-api
serviceCatalogApiProvider = setCustomBaseUrl("http://localhost:8080/tmf-api/serviceCatalogManagement/v4");
var serviceCatalogApiConsumer = new ServiceCatalogApi();
// base address of the local consumer tmforum-api
serviceCatalogApiConsumer = setCustomBaseUrl("http://localhost:8081/tmf-api/serviceCatalogManagement/v4");
The Access-Node repository uses a CI-Pipeline to deliver the Helm-Chart as a tested and versioned component.
The CI is set up as following:
- integration-tests are executed on every push
- on every PR to
main, the CI checks if anything inside the/charts/access-nodefolder was changed- if false: skip release and allow merging to main
- if true:
- generate the new version, based on the tag assigned to the PR(patch,minor,major)
- set the version to the Chart.yaml, postfixed with
-PRE-<PR_NUMBER>following the SemVer 2.0 Spec - generate the updated documentation
- add the chart to the pre-repo(https://dome-marketplace.github.io/access-node/pre)
- on push-to-main(e.g. merged PR), the CI checks if anything inside the
/charts/access-nodefolder was changed- if false: skip release and allow merging to main
- if true:
- generate the new version, based on the tag assigned to the PR(patch,minor,major)
- set the version to the Chart.yaml
- generate the updated documentation
- add the chart to the helm-repo(https://dome-marketplace.github.io/access-node)
- create a tag and a GitHub release