Skip to content

Telemetry

The ICOS Telemetry is the ICOS module that is responsible for collecting the status and the performance of resources (hardware, system, containers, processes) at the host level (device, board, Virtual Machine).

This component is mandatory and must be installed in all the edge hosts that are part of the ICOS Continuum (e.g., all the K8s clusters in OCM, all the devices registered in Nuvla).

Telemetry modules are distributed across the continuum realizing a network of nodes that send, forward and store data. On edge devices, the Telemetruum Leaf component must be installed. The Telemetruum Leaf needs to connect to the Telemetruum Gateway module (deployed in the ICOS Agents) to send the data collected using either HTTP or gRPC protocols. For this reason, outgoing connectivity should be ensured from the Telemetry Leaf to the ICOS Agent.

The two main configuration parameters that needs to be known before starting with the installation are: - the Telemetruum Gateway Endpoint: the endpoint where to send the metrics collected, - the ICOS CA Root Certificate Bundle. This is required only if the Gateway endpoint is exposed on a HTTPS endpoint.

Depending on the technology used, two installation methods are available (see below).

OCM-Kubernetes Installation

The installation of the Telemetruum Leaf in a Kubernetes (or compatible) cluster is done using the Telemetruum Leaf Helm Chart.

As a prerequisite, Helm must be installed to use the chart (follow the instructions in the Helm's documentation to get started).

The Helm Chart accepts many values that can be used to customize the installation and enable/disable some features. More documentation can be found on GitHub.

Step 1 - Configure and Install

  1. Create a values.yaml file with the following content:

telemetruumGatewayEndpoint: https://telemetry.my-agent.com/
# only needed for Telemetruum Gateway exposed on HTTPS endpoints
extraCerts:
  # the certifictes bundle must be encoded in base64
  bundle: LS0tLS1CRUdJTiBD...IENFUlRJRklDQVRFLS0tLS0K
Run the Helm installation command (making sure that the correct kubernetes config file is taken):

helm install --namespace icos-system --create-namespace tlum-leaf oci://harbor.res.eng.it/icos/helm/telemetruum-leaf --values values.yaml
Note

This command uses the default Kubernetes kubeconf file (the same used by kubectl). To change it, either define a new location with the KUBECONFIG environment variable (e.g., export KUBECONFIG=/my/location) or use the helm kubeconfig /my/location flag.

Upgrade

In order to upgrade the Telemetruum Leaf to the latest version, run the same command replacing install with upgrade.

Step 2 - Verify

If the installation is successful, multiple pods are created (the number depends on the number of nodes in the cluster and the configuration options). At least a prometheus-node-exporter, an otel-node-agent, and one otel-target-allocator pod should be up and running. 

kubectl get pods -n icos-system

NAME                                                              READY   STATUS    RESTARTS   AGE
generic-device-plugin-glpfq                                       1/1     Running   0          22m
nfd-prom-exporter-85f66bb788-kc5d5                                1/1     Running   0          22m
tlum-leaf-prometheus-node-exporter-std26                          1/1     Running   0          22m
tlum-leaf-telemetruum-leaf-otel-target-allocator-67d7d59fbthgvz   1/1     Running   0          22m
nfd-master-65c55894f7-ffkrx                                       1/1     Running   0          22m
nfd-worker-89gtd                                                  1/1     Running   0          22m
tlum-leaf-kube-state-metrics-6cb98ddd74-fjkw4                     1/1     Running   0          22m
tlum-leaf-telemetruum-leaf-telemetruum-leaf-exporter-6wlsq        1/1     Running   0          22m
tlum-leaf-telemetruum-leaf-otel-node-Leaf-k7q4h                  1/1     Running   0          22m
If data is sent correctly to the ICOS Controller, the new host should be visible in the Grafana dashboard. Errors related to the transmission of data can be troubleshooted by looking at the logs of the otel-node-agent pod.

Development version

Note: In order to install versions not yet released, the url of the chart needs to be changed to 

oci://harbor.res.eng.it/icos-private/helm/telemetruum-leaf

In addition, since unreleased versions are private, you need to login to the repository before launching the install command: 

helm registry login harbor.res.eng.it/icos-private/helm and provide your credentials.

Nuvla Installation

In the case that the Docker version of NuvlaEdge is being used, the ICOS Telemetruum Leaf is Available as a Nuvla App. The general procedure to deploy and run an App on a NuvlaEdge can be found at: https://docs.nuvla.io/nuvla/user-guide/run-app/.

The Telemetruum Leaf can be installed directly from the Nuvla UI. Assuming that the Docker NuvlaEdge is already installed (see Section YYY):

  • Login to nuvla.io
  • Switch to the ICOS group
  • Select Apps
  • Select the ICOS Telemetruum Leaf - Docker or ICOS Telemetruum Leaf - Kubernetes App (depending on the type of Edge device):

NuvlaEdge

When making the deployment, some environment variables need to be filled in:

  • ICOS_TELEMETRUUM_GATEWAY_ENDPOINT: the endpoint for the Telemetruum Gateway
  • ICOS_TELEMETRUUM_EXTRA_CERTS: <the ICOS CA Root Certificate Bundle in Base64.
    • For the Docker app, it is not a variable but a configuration file to override named extracertsbundle.pem - the content must be in PEM format)

Other variables are available to further customize the installation.

NuvlaEdgeTeleMeteryAgentDocker

Once deployed, you can check on the NuvlaEdge node that some docker containers have got started:

NuvlaEdgeStarted