Access Node
The DOME Access-Node is a set of services, that can be used to access the DOME Marketplace. A registered participant can use it to act as a federated marketplace in DOME.
The Access-Nodes consists of 3 logical building blocks:
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.
TODO: Add description of blockchain connector
Overview and sub-components
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 a 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.
Infrastructure requirements
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 Pod | 250 |
| Scorpio | 400 |
| Postgresql/Postgis | 150 |
| Redis | 10 |
Apart from the database service, no other service will maintain a own persistence, therefor only for this service a persistent volume claim has to be dimensioned.
How to deploy
The recommended and endorsed way of deployment is via the provided helm charts ( optionally wrapped in ArgoCD Applications).
To deploy a setup, the umbrella chart of the access-node can be used as followed:
-
create a configuration values file according to the own environment, as described here.
-
add helm chart repository to helm installation
helm repo add dome-access-node https://dome-marketplace.github.io/access-nodehelm 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 components using the prepared configuration
helm install <RELEASE_NAME> dome-access-node/access-node --namespace <NAME_SPACE> --version <CHART_VERSION> -f values.yaml
How to configure
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 respective charts of the components should be consulted.
TODO: Replace with charts in once they are used.
To have a starting point, the this minimal config reduces the configuration to items that are likely changed by integrators. TODO: include config for the blockchain components
How to validate a deployment
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
How to operate
- 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.
TODO: Prometheus Metrics TODO: Grafana Dashboard
How to update
Upgrade to both a different chart version and new configuration can be accomplished with the following command
Release process
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
Troubleshooting
To be filled once feedback from integrators comes in
Timeouts occur while querying TM-Forum-API
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.