Data broker

Find out about the installation of the Messaging Service and the microservice-based data broker on Cumulocity Edge.

Installing the Messaging Service and the microservice-based data broker

The microservice-based data broker is an optional component of Edge. The data broker is a Cumulocity feature that allows a Cumulocity tenant to send data in motion (live measurements, events and alarms), using the standard Cumulocity REST API requests, to another tenant as that data arrives in the first tenant. It is often used to ‘ship’ data from remote Edge Cumulocity instances in the field to a central Cumulocity instance, where all data from all remote ‘field’ locations can be seen and handled together. Another use case is when devices are leased. The devices are managed by the leasing company in its tenant, and the devices’ measurements and other data are sent to the leasing tenant via a data broker connection for application data processing.

The bundle for installing the Messaging Service and the microservice-based data broker comes as a .tgz file which contains the Messaging Service and data broker files, an install script and a digital signature. This bundle is unpacked, the signature verified and the install script executed by another script that is part of the standard Edge installation. The bundle can be downloaded from the Cumulocity Download Center. The bundle is named “Cumulocity Data Broker Edge”.

Requirements

Ensure that microservice hosting feature is enabled for Edge as both the Messaging Service and data broker run as Kubernetes pods. Running microservices on a basic Edge installation requires the number of CPU cores to be increased from 2 to 4 and the RAM to be increased from 6GB to 8GB. Running the Messaging Service and data broker requires an extra 4GB of RAM on top of this.

The Messaging Service microservice uses API version 1. To install the Messaging Service on Edge version 10.15, you must subscribe the “edge” tenant to the Feature-privileged-microservice-hosting application before uploading the Messaging Service microservice with API version 1. For more information, see Deploying microservices with a lower manifest version.

Using SCP, copy the bundle to the /tmp directory on the Edge server. Enter the password for the Edge Linux administrative/login account when prompted. For example:

scp pulsar-edge-install-1018.0.0.tgz	 "<LOGIN_USERNAME>@<DNS_NAME_OF_SERVER>:/tmp/"

Substitute the relevant values of <LOGIN_USERNAME> and <DNS_NAME_OF_SERVER>. Then run:

ssh <LOGIN_USERNAME>@<DNS_NAME_OF_SERVER> -t "/bin/bash -c 'cd /tmp && sudo /opt/c8y/utilities/install_signed_package.sh /tmp/pulsar-edge-install-1015.0.0.tgz"

Enter the Edge Linux admin account password, again followed by the Cumulocity admin account password.

To confirm the Messaging Service and data broker are now running, log into the Edge VM using SSH with the connection details used previously and run:

sudo kubectl get pods -A

The command returns something like this:

NAMESPACE                NAME                                                             READY   STATUS      RESTARTS   AGE
c8y-messaging-service    pulsar-bookie-0                                                  1/1     Running     0          4m14s
c8y-messaging-service    pulsar-bookie-init-765k9                                         0/1     Completed   0          4m14s
c8y-messaging-service    pulsar-broker-0                                                  1/1     Running     0          4m14s
c8y-messaging-service    pulsar-pulsar-init-z97xs                                         0/1     Completed   0          4m14s
c8y-messaging-service    pulsar-zookeeper-0                                               1/1     Running     0          4m14s
calico-system            calico-kube-controllers-5ddcc6fc8f-sln6x                         1/1     Running     0          82m
calico-system            calico-node-bxm9b                                                1/1     Running     0          82m
calico-system            calico-typha-7fd9df674f-24zwz                                    1/1     Running     0          82m
cumulocity-single-node   databroker-agent-server-scope-edge-deployment-7dc4dbdc5f-wxh8l   1/1     Running     3          3m36s
cumulocity-single-node   device-simulator-scope-management-deployment-78d5c6694-rlpjx     1/1     Running     0          80m
cumulocity-single-node   kube-registry-persistent-secure-7db46f57b5-vhlbh                 1/1     Running     0          81m
kube-system              coredns-74ff55c5b-5zkps                                          1/1     Running     0          82m
kube-system              etcd-localhost                                                   1/1     Running     0          82m
kube-system              kube-apiserver-localhost                                         1/1     Running     0          82m
kube-system              kube-controller-manager-localhost                                1/1     Running     0          82m
kube-system              kube-proxy-92lm6                                                 1/1     Running     0          82m
kube-system              kube-scheduler-localhost                                         1/1     Running     0          82m
kube-system              metrics-server-5b78d5f9c6-7l45k                                  1/1     Running     0          82m
tigera-operator          tigera-operator-76bbbcbc85-6clrf                                 1/1     Running     0          82m

The key pods that should be running are pulsar-bookie-0, pulsar-broker-0, pulsar-zookeeper-0 and databroker-agent-server, with a suffix for the pod name specific to the installation. It may take a few minutes for the Kubernetes pods to settle into a running state after the installation has been completed.

For more information on installing and troubleshooting the Messaging Service, see the Messaging Service installation & operations documentation] available on the Cumulocity Download Center (credentials required).

For more information on configuring and using the microservice-based data broker, see Microservice-based data broker.

Uninstalling the Messaging Service and the microservice-based data broker

The bundle for the Messaging Service and data broker microservice does not have an uninstall command. If a mistake is made or an installation fails, the bundle components must be uninstalled manually. Afterwards, the installation can be reattempted.

To uninstall manually

Login to Edge using SSH.
Uninstall the Pulsar Helm chart.

sudo helm uninstall pulsar -n c8y-messaging-service

Wait for the pulsar pods to terminate.
This command updates its state every two seconds. When it reports that there are no resources, press Ctrl+C to return to the command line.

watch sudo kubectl get pods -n c8y-messaging-service

Delete Pulsar’s persistent volume claims.

sudo kubectl delete pvc -n c8y-messaging-service --all

Find the names of the persistent volumes used by the Pulsar components.

Here the grep command is used to filter the output. The names are in the output’s leftmost column.

sudo kubectl get pv | grep pulsar
journal0     2Gi        RWO            Retain           Released    c8y-messaging-service/pulsar-bookie-journal-pulsar-bookie-0      local-storage            3h
ledgers0     10Gi       RWO            Retain           Released    c8y-messaging-service/pulsar-bookie-ledgers-pulsar-bookie-0      local-storage            3h
zookeeper0   2Gi        RWO            Retain           Released    c8y-messaging-service/pulsar-zookeeper-data-pulsar-zookeeper-0   local-storage            3h

Delete each of the persistent volumes found in the previous step.

sudo kubectl delete pv journal0 ledgers0 zookeeper0

Delete the directories used by the persistent volumes.

sudo rm -rf /opt/bookie/ledgers /opt/bookie/journal /opt/zookeeper

Unsubscribe the “edge” tenant from and delete, the databroker-agent-server microservice.

The databroker-agent-server application ID is required for the HTTP requests used to do both of these.
To find its application ID, you can use a cURL command of the following form and redirect the output to a jq command to make it easier to read the JSON response. The general structure of the command is:

curl http://<EDGE-HOSTNAME>/application/applicationsByName/databroker-agent-server -su <TENANT>/<USERNAME> | jq --indent 2

The ID required is the value of the id field at the root level of the JSON response. In the following example, it has the value ‘19’ (the penultimate JSON field).

curl http://myown.iot.com/application/applicationsByName/databroker-agent-server -su edge/admin | jq --indent 2
Enter host password for user 'edge/admin':
{
  "next": "https://myown.iot.com/application/applications?pageSize=5&currentPage=2",
  "self": "https://myown.iot.com/application/applications?pageSize=5&currentPage=1",
  "statistics": {
    "pageSize": 5,
    "currentPage": 1
  },
  "applications": [
    {
      "owner": { ... truncated ... },
      "requiredRoles": [ ... truncated ... ],
      "manifest": { ... truncated ... },
      "roles": [],
      "contextPath": "databroker-agent-server",
      "availability": "MARKET",
      "type": "MICROSERVICE",
      "activeVersionId": "1345",
      "name": "databroker-agent-server",
      "self": "https://myown.iot.com/application/applications/19",
      "id": "19",
      "key": "databroker-agent-server-key"
    }
  ]
}

Use that ID value in the request to unsubscribe from the microservice and again when deleting it.

To unsubscribe, use a command of the following form:

curl -X DELETE http://<EDGE-HOSTNAME>/tenant/tenants/<TENANT>/applications/<APP-ID> -u <TENANT>/<USERNAME> -v

This returns an HTTP 204 (no content) response. For example:

curl -X DELETE http://myown.iot.com/tenant/tenants/edge/applications/19 -u edge/admin -v
Enter host password for user 'edge/admin':
* About to connect() to myown.iot.com port 80 (#0)
*   Trying 127.0.0.1...
* Connected to myown.iot.com (127.0.0.1) port 80 (#0)
* Server auth using Basic with user 'edge/admin'
> DELETE /tenant/tenants/edge/applications/19 HTTP/1.1
> Authorization: Basic ZWRnZS9hZG1pbjpFZGdlN184OV9fX19fX18=
> User-Agent: curl/7.29.0
> Host: myown.iot.com
> Accept: */*
>
< HTTP/1.1 204 No Content
< Date: Thu, 07 Sep 2023 16:27:32 GMT
< Connection: keep-alive
< X-Content-Type-Options: nosniff
< X-XSS-Protection: 1; mode=block
< Cache-Control: no-cache, no-store, max-age=0, must-revalidate
< Pragma: no-cache
< Expires: 0
< X-Frame-Options: DENY
<
* Connection #0 to host myown.iot.com left intact

To delete, use a command of the following form:

curl -X DELETE http://<EDGE-HOSTNAME>/application/applications/<APP-ID> -su <TENANT>/<USERNAME> -v

This returns an HTTP 204 (no content) response. For example:

curl -X DELETE http://myown.iot.com/application/applications/19 -su edge/admin -v
Enter host password for user 'edge/admin':
* About to connect() to myown.iot.com port 80 (#0)
*   Trying 127.0.0.1...
* Connected to myown.iot.com (127.0.0.1) port 80 (#0)
* Server auth using Basic with user 'edge/admin'
> DELETE /application/applications/19 HTTP/1.1
> Authorization: Basic ZWRnZS9hZG1pbjpFZGdlN184OV9fX19fX18=
> User-Agent: curl/7.29.0
> Host: myown.iot.com
> Accept: */*
>
< HTTP/1.1 204 No Content
< Date: Thu, 07 Sep 2023 16:35:11 GMT
< Content-Type: application/vnd.com.nsn.cumulocity.error+json;charset=UTF-8;ver=0.9
< Connection: keep-alive
< X-Content-Type-Options: nosniff
< X-XSS-Protection: 1; mode=block
< Cache-Control: no-cache, no-store, max-age=0, must-revalidate
< Pragma: no-cache
< Expires: 0
< X-Frame-Options: DENY
<
* Connection #0 to host myown.iot.com left intact