Connecting Edge to the cloud

Edge can be managed, configured, and monitored remotely through a Cumulocity cloud tenant. You can control and troubleshoot your instance of Edge deployments remotely.

Registering Edge in the cloud tenant

To remotely manage, configure, and monitor Edge through a Cumulocity cloud tenant, you must first register it as a device within the cloud tenant. This registration process requires providing the Cumulocity cloud tenant URI, along with an optional TLS/SSL key and certificate chain. These credentials authenticate Edge when connecting to the cloud via the MQTT protocol using X.509 certificate-based authentication. You can configure the cloud tenant URI, TLS/SSL key, and certificate chain using the spec.cloudTenant field in the Edge CR. For more details, refer to Edge Custom Resource - Cloud Tenant.

If you do not provide a TLS/SSL key and certificate chain, the Edge operator automatically generates an internal TLS/SSL key and certificate for authentication. In this case, Edge will identify itself using the domain name of the instance.

To complete the registration process, you must sign in to your cloud tenant and follow the steps outlined in Managing trusted certificates to add the appropriate Certificate Authority (CA) certificate to your tenant’s trusted certificate list.

If Edge uses an internally generated TLS/SSL key and certificate, you can download the corresponding CA certificate by running the following command:

kubectl get edge c8yedge -n c8yedge --output jsonpath='{.status.helpCommands.fetchGeneratedCACrt}' | sh
Info
Substitute the Edge name and namespace name c8yedge in the command above with the specific Edge name and namespace name you have specified in your Edge CR.

Once registered, the Edge instance appears as a device in the cloud tenant. The device name is determined by the Common Name (CN) specified in the TLS/SSL certificate used for authentication. If you provided a custom TLS/SSL key and certificate, the device name matches the CN. However, if the Edge operator generated the TLS/SSL certificate internally, the device name defaults to the domain name of the Edge. For example, if your Edge instance is configured with the domain myown.iot.com, it will appear as a device named myown.iot.com in the cloud tenant. Once registered, you can remotely access your Edge instance, monitor its metrics, perform version upgrades, and collect diagnostic data for troubleshooting and analysis.

Upgrading Edge remotely

You can remotely update your instance of Edge using the Cumulocity’s firmware update feature. This process requires you to upload a YAML file specifying the Edge version to your tenant account. For more information about the firmware feature, see Managing firmware.

Update the sample version file to specify the Edge version follow the steps below to upgrade:

  1. Log in to your Cumulocity tenant account and go to the Device Management application.

  2. In the Firmware repository page, click Add firmware and provide a name for the firmware, add a description and its version (all required).

    Firmware list

    Optionally, you can define the device type filter when adding a new firmware. For example, c8y_EdgeAgent.

  3. Select the Provide a file path option to specify an HTTPS URL of a server from where the version file can be downloaded.

    Click Add firmware. The firmware object appears in the firmware list.

  4. Click All devices in the Devices menu, select your instance of Edge from the device list.

  5. Click Firmware. The Firmware tab shows the current Edge version.

    Edge version

    You can also see the current Edge version in the Info tab.

    Edge version

  6. Click Replace firmware.

  7. Select the firmware that you just uploaded and click Install. Edge version

    • To check the status of the update, hover over the refresh icon as shown in the figure below: Edge version
    • To check the details of the update, click the text outlined in red in the figure below: Edge version

Updating Edge appliances using bulk operations

For information about updating Edge using bulk operations, see Updating Edge using bulk operations.

Downloading diagnostics remotely

You can download the diagnostics report remotely from your tenant account after you have registered your instance of Edge in the tenant account.

To download the diagnostics report from your tenant account:

  1. Log in to your Cumulocity tenant.

  2. Go to the Device Management application.

  3. Click Devices > All devices in the navigator.

  4. Select your instance of Edge for which you want to download the diagnostics report.

  5. Click Diagnostics > Request diagnostic file.

    Diagnostics report remotely

  6. Click the ZIP file link to download the diagnostic report.

Managing software remotely

You can remotely manage the applications, microservices and extensions installed on Edge using the Cumulocity advanced software management feature. This process requires you to first upload an application, microservice or extension to the software repository before installing them. For more information on uploading items to the software repository, see To add a new software or software version. For more information about the software management feature in general, see Managing device software.

Important
To use the Cumulocity advanced software management feature, your Cumulocity cloud tenant’s subscription plan must include the advanced-software-mgmt microservice.
  • Applications - You need a Cumulocity application, see Web SDK for details. Upload the application zip to the software repository with the software type c8yedge_application
  • Microservices - You need a microservice, see Microservice SDK for details. Upload the microservice zip to the software repository with the software type c8yedge_microservice
  • Extensions - You need either a widget or plugin, see Micro frontends for details. Upload the extension zip to the software repository with the software type c8yedge_extension
Info
When using the remote software management feature, the manifest for applications, microservices and extensions must contain a name, key, version and contextPath. These values are used when installing the software rather than using the name and version from the software repository. The name and version from the manifest are also listed on the devices Software tab when installed.

Installing software

  1. Navigate to your Edge device’s Software tab. The Software tab lists your installed applications, microservices and extensions. Click Install software. The Install software dialog lists the software from the software repository which matches Edge’s supported types of c8yedge_application, c8yedge_microservice and c8yedge_extension.
  2. Select one or multiple software items.
  3. Click Install.
  4. Under Software changes on the right, review your planned changes and confirm the software update operation by clicking Apply changes.

The install operation will be created and executed on the device. The software installation is completed when the device has installed the software.

Info
Applications and microservices will be installed and subscribed to on your ’edge’ tenant but extensions will only be installed.

Updating software

To update software on your Edge device, hover over the software item which you want to update and click Update. Select a version from the list and click Update again. The software will be updated with the selected version.

The update operation will be created and executed on the device. The software update is completed when the device has updated the software.

Removing software

To remove software on your Edge device, hover over the software item which you want to remove and click the remove icon.

The remove operation will be created and executed on the device. The software removal is completed when the device has removed the software.

Data exchange using data broker

Data broker lets you upload the data to a Cumulocity tenant account selectively. Note that you must first create a Cumulocity tenant account.

You can share the following data with the tenant account:

  • Devices (and more generically, managed objects)
  • Events
  • Alarms
  • Measurements
  • Operations
Info
Devices, events, alarms, and measurements are forwarded from Edge to the Cumulocity tenant account. In contrast, operations are forwarded from the Cumulocity tenant account to Edge, but only for devices that exist in the Cumulocity tenant account due to forwarded data.

To upload the data to a Cumulocity tenant account, you must first create a data connector in the Edge appliance and subscribe this connector in the tenant account.

A data connector describes the subset of the data that you would like to send to the Cumulocity tenant. For more information, see Data connectors.

To create a data connector and upload the data to the tenant account, perform the following steps:

  1. Log in to the “edge” tenant. For more information, see To access Edge

  2. Navigate to the Administration application. Click Data broker > Data connectors.

  3. Click Add data connector and provide all the information and filters. See To add a data connector.

    Note down the security code. This security code will be used to subscribe the connector in the tenant account.

  4. Log in to the Cumulocity tenant account.

  5. In the tenant account, go to the Administration application. Click Data broker > Data subscriptions to subscribe the connector created in your Edge appliance.

    Click Add data subscription and provide the security code. Click Submit and accept the subscription. See Data subscriptions.

    You can now navigate to the Device Management application or the Cockpit application. You will find a new “virtual group” with a specific icon showing the forwarded devices. The group will have the same name as your subscription.

For more information about sending and receiving data in Cumulocity, see Using the data broker.