Context
Change Type: API change
Product area: Platform services
Component: MQTT
Deployed at: eu.latest.cumulocity.com, apj.cumulocity.com, jp.cumulocity.com, cumulocity.com, us.cumulocity.com, emea.cumulocity.com
Technical details
Build artifact: mqtt-service (0.9.6)
Description
Caution
This change only affects the new Cumulocity MQTT Service capability.
The existing Cumulocity Core MQTT capability is not affected.
Introduction
As previously announced, when the Cumulocity MQTT Service transitions from Public Preview to General Availability (GA), the MQTT Service will enforce device isolation.
MQTT devices will be able to subscribe to any topic, but will not automatically receive messages published to that topic by other devices.
Microservices will be able to explicitly route messages between different devices.
In effect, each MQTT client identifier will have its own private topic space that is not shared with other clients, but can be accessed by microservices.
Info
Device isolation is enabled by default for any tenant using the MQTT Service for the first time.
Tenants already using the MQTT Service can continue to use the deprecated tenant isolation approach, but should migrate their applications to work with device isolation as soon as possible.
A feature toggle is available to allow these tenants to switch between isolation models while updating their applications.
We are making this change to align the MQTT Service with the behavior of the existing Core MQTT capability, and to improve out-of-the-box security for typical IoT applications where direct inter-device communication is not required.
Device versus tenant isolation
The difference between the two isolation models can be explained using a simple example.
Assume that a tenant has two MQTT clients connected to the MQTT Service, with client identifiers publish-client and subscribe-client, and that subscribe-client has subscribed to the topic my-topic.
Then, publish-client publishes a message to my-topic:
- If the tenant is using device isolation,
subscribe-clientwill not receive that message. - If the tenant is using tenant isolation,
subscribe-clientwill receive the message.
A microservice can receive all messages published by all MQTT clients, and choose whether to forward messages to other clients.
Impact on MQTT devices and microservices connecting to the MQTT Service
This is a breaking change and affected applications must be updated to continue working after the GA version of the MQTT Service is deployed.
This change affects any application where MQTT devices exchange messages by publishing and subscribing to the same topics.
In particular it affects applications where a Cumulocity microservice connects to the MQTT Service using the MQTT protocol to exchange messages with connected MQTT devices.
Existing microservices that are affected by this change should not immediately migrate to the existing Java client SDK, as this will not be supported in the GA version.
Instead, these microservices should wait for the new MQTT Service API to be released and migrate directly to this API.
Details of the new API and how to use it in microservices will be announced soon.
Switching between isolation models
Tenants can switch between the device and tenant isolation models using the mqtt-service.tenant.isolation feature toggle.
The feature toggle is set to true by default for tenants that are already using the MQTT Service, to maintain the deprecated tenant isolation behavior.
These tenants can use the feature toggle to switch between isolation modes while developing and testing their migration to device isolation.
For all other tenants, the feature toggle is set to false and should not be changed.
To set the feature toggle to false, the following HTTP PUT request must be sent to the tenant.
This example uses the curl command, but any equivalent tool that can send HTTP requests can be used:
curl --location --request PUT "https://<TENANT_DOMAIN>/features/mqtt-service.tenant.isolation/by-tenant" \
--header "Authorization: Basic <AUTHORIZATION>" \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data-raw '{ "active":false }'
Where <TENANT_DOMAIN> is the domain name of the tenant, for example my-tenant.cumulocity.com, and <AUTHORIZATION> is a Base64-encoded HTTP Basic Authentication token for the tenant, constructed as described in the API documentation.
A similar request can be sent to set the feature toggle back to true:
curl --location --request PUT "https://<TENANT_DOMAIN>/features/mqtt-service.tenant.isolation/by-tenant" \
--header "Authorization: Basic <AUTHORIZATION>" \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data-raw '{ "active":true }'