Appearance
Move from the legacy agent to the modern agent #
Decide and stage a legacy-to-modern agent migration without treating a working field fleet as a disposable test environment.
Do not migrate merely because the modern agent exists. The legacy agent remains actively supported, and Dataplicity applies no pressure to force an update. Migrate when the new operating model solves a real problem and you can qualify the change on the same hardware and image conditions found in the field.
A sensible split #
| Cohort | Default decision |
|---|---|
| Stable remote-access-only devices on an old image | Keep legacy and maintain the runbook |
| New product image | Integrate modern |
| Existing devices that need streams, settings, actions or Class Software | Plan a modern migration |
| A/B image product | Make the modern runtime part of the signed image |
| Unusual custom/Yocto fleet | Build and prove an image-specific integration before scheduling field rollout |
One Dataplicity organisation can contain both generations. Tag or record the generation and install mode so support automation selects the right commands.
Treat migration as five separate proofs #
- Compatibility - the modern rescue and supervisor run on the exact OS, architecture, service manager and storage layout.
- Identity - the intended device record and ownership survive, or the replacement identity is deliberately reconciled.
- Access - Remote Shell, Wormhole, file access and permissions still match the support model.
- Product path - broker, settings, actions and optional Class Software work under loss, reboot and duplicate delivery.
- Recovery - the device can return to a known-good image or service state without a site visit.
Stage the rollout #
Start with bench hardware, then a field canary from the oldest or most awkward supported image - not only the newest unit in the office. Expand by explicit cohorts and stop on identity churn, reconnect regression, permission widening, persistent-state loss or unexplained resource growth.
Keep the legacy recovery instructions available until the modern cohort has survived reboot, network loss and a normal release cycle.
Do not smuggle in unrelated changes #
Avoid combining the agent migration with a new base OS, new container runtime, filesystem redesign and product-application rewrite in one rollout. If they must ship together in a signed image, validate each boundary and the combined image explicitly.
For implementation, continue with Integrate the modern agent. For an existing classic cohort, retain the legacy runbook until migration is complete.