Introducing Device migration, an open-source add-on for Cumulocity

News Open-Source news
, ,
1

Device migration is a new open-source add-on that moves a complete device hierarchy from one Cumulocity tenant to another. It copies the managed objects with all their fragments, their parent and child relationships, their external identities, and, if you want, their measurements, events, and alarms. The add-on consists of a microservice and a UI plugin for the Administration application. A command line tool performs the same migration from your own machine.

Typical reasons to move devices between tenants:

  • From test to production: Devices are commissioned in a test tenant and then move to the customer tenant with their recent data.
  • Changing tenant structures: When customers, sites, or business units are reorganized, their devices follow with their history and identities.
  • Consolidating or splitting tenants: Fleets are combined in one tenant or distributed across several, also across parent tenants and instances.

The add-on provides several advantages:

  • Check before anything moves: A live data preview shows what a migration creates, and limits stop one that is too large before it starts.
  • The source stays intact: A migration is a copy. Devices, data, and identities remain in the source tenant.
  • Every migration can be undone: All objects a migration creates carry a run marker, and a revert deletes the objects that carry it.
  • Devices can reconnect: A migration can provide new credentials or move the trust anchor of a certificate fleet.

Installation

The add-on is installed in a parent tenant, either the management tenant or an enterprise tenant, and migrates between the tenants subscribed to it.

  1. Download the microservice (devicemigration-<version>.zip) and the UI plugin (devicemigration-ui-<version>.zip) from the releases page.
  2. In the parent tenant, upload the microservice under Administration → Ecosystem → Microservices and the plugin under Administration → Ecosystem → Extensions, then add the plugin to the Administration application.
  3. Subscribe the parent tenant to the microservice first, then the source and target tenants.
  4. Assign the ROLE_DEVICE_MIGRATION_ADMIN role to the users of the parent tenant who should run migrations.

Device migration then appears in the navigator of the Administration application.

Migrating devices

The video above shows a complete migration. The list shows every migration with its source and target tenant, status, user, and run ID. Expanding a row shows the scope: the relationships that were followed, the device data and its time window, and how the devices got credentials.

The list of migrations with an expanded row
The list of migrations with an expanded row3200×2200 403 KB

To start a migration, click New migration:

  1. Choose the source tenant, then pick a group or a single device in the platform’s asset selector. Child assets and devices are included.
  2. Choose the target tenant and the device data: measurements, events, and alarms. The start date accepts a relative window such as -14d or an absolute date and is checked as you type.
  3. (Optional) Choose how the migrated devices authenticate (see Migrating device credentials below).
  4. Check the data preview of the objects, identities, device users, and records the migration creates, against the configured limits.

Starting a new migration with the data preview
Starting a new migration with the data preview3200×2200 389 KB

Start migration runs the migration as a job, and its row shows the progress. Once it has finished, the Migration log in the row menu shows what it did, object by object. Revert in the same menu undoes it: every object the migration created carries a marker fragment with its run ID, and the revert deletes these objects after you confirm. The row keeps a record of the undo.

Migrating to a tenant that is not connected

The target list offers the tenants subscribed to the microservice, which share the parent tenant. For a tenant under a different parent tenant or on a different Cumulocity instance, select Connect a different tenant… in the target list:

  1. Enter the host and the tenant ID of the target tenant. The microservice creates a certificate for this connection and shows its public CA certificate.
  2. Register the certificate as trusted, with auto-registration enabled, in the target tenant. If the plugin is installed there, an administrator of the target tenant pastes it on the Trust a migration certificate screen under Device migration. Otherwise, download the certificate and add it under Trusted certificates in Device management.
  3. Start the migration as usual. The microservice reaches the target tenant with the certificate, so it needs no credentials for it, and the private key never leaves the microservice.

Such a connection cannot create device users, so only No credentials and They keep their existing certificates are offered. A revert from the list is possible while the certificate is valid, for six hours. After that, revert with the command line tool.

Migrating device credentials

A migration copies the digital twins, but the device credentials belong to the source tenant. The New migration dialog therefore asks how the migrated devices authenticate:

  • No credentials: Only the twins are migrated, and the devices get credentials in the target tenant by other means.

  • New credentials, provided as download: The migration creates a device user for every device in the target tenant. The user who started the migration downloads the passwords as a CSV file with Download device credentials in the row menu, once and within one hour. Getting them onto the devices is up to you.

  • Devices collect new credentials: Each device asks the microservice for its new credentials with the credentials it has for the source tenant, and receives the host, tenant, user name, and password for the target tenant once:

    curl -X POST -u "$TENANT/device_$SERIAL:$PASSWORD" \
    "https://$SOURCE_HOST/service/devicemigration/devices/self/migration"

    This requires devices with a device user of their own, so it does not cover child devices behind a gateway.

  • They keep their existing certificates: For a certificate fleet, the migration makes each object owned by the device user its certificate will authenticate as. Move trust anchor in the row menu then moves the trusted certificate to the target tenant, and the devices arrive there when they reconnect. Expect a short interruption, because a certificate can be trusted by only one tenant per instance.

A migration that creates device users is refused if the target tenant already has a device with one of the same external IDs, which the dialog checks before you start. A revert also deletes the device users. Apart from a trust anchor move, the devices keep working credentials in the source tenant.

Using the command line tool

The command line tool c8y-devicemigration performs the same migration without the microservice. It uses the session files of the Cumulocity CLI, including encrypted ones, without needing an active session. Download it for macOS, Linux, or Windows from the releases page.

Check that two sessions point at different tenants and that their credentials work:

c8y-devicemigration preflight \
    --sourceSession source.eu-latest.cumulocity.com-me.json \
    --targetSession target.eu-latest.cumulocity.com-me.json

Migrate a hierarchy with the measurements, events, and alarms of the last 30 days. The tool names both tenants and asks before it creates anything, and --incremental moves the data one device at a time:

c8y-devicemigration migrate --rootId 12345 \
    --sourceSession source.eu-latest.cumulocity.com-me.json \
    --targetSession target.eu-latest.cumulocity.com-me.json \
    --dataTypes all --dateFrom -30d --incremental

Create a device user for every migrated device and write the passwords to a file:

c8y-devicemigration migrate --rootId 12345 \
    --sourceSession source.json --targetSession target.json \
    --credentials --credentialsFile ./credentials.csv

Export and import as separate steps, for example when no single machine can reach both tenants:

c8y-devicemigration export --rootId 12345 --output-directory ./export \
    --dataTypes measurements,events --session source.json

c8y-devicemigration import --input-directory ./export --session target.json

Undo a migration with the mapping file the import wrote, or by its run ID:

c8y-devicemigration revert --mapping id_mapping.json --session target.json
c8y-devicemigration revert --runId 20261007T074212Z_9c41e0 --session target.json

Notes and limitations

  • Operations are not migrated, because recreated operations would arrive as pending and be executed by the devices again. Device protocols, data offloaded to the data lake, audit logs, binaries attached to managed objects, applications, tenant options, users, and roles are not migrated either.
  • Smart rules and EPL apps in the target tenant react to imported data, and retention rules can delete imported history. Deactivate the rules and adjust the retention rules before importing data.
  • A migration is limited to 25 child objects and, per device, 1,000,000 measurements and 1,000 events or alarms. Measurements default to the last 14 days.

Summary

The Device migration add-on moves device hierarchies between Cumulocity tenants from the Administration application, with a preview before it starts, a log of what it did, and an undo afterwards. Credentials and certificate fleets can come along, and the target can be on another instance. The command line tool covers the same migration for scripts and one-off tasks.

We are already working on additional capabilities, and if you would like to contribute, the project is available here:

The Device migration add-on is provided as-is and without warranty or support. It does not constitute part of the Cumulocity product suite. Users are free to use, fork, and modify it, subject to the license agreement. While Cumulocity GmbH welcomes contributions, we cannot guarantee to include every contribution in the master project.

5 Likes