Hosted-mender-migration

reference

Mender team offers two public instances for the Mender software: hosted Mender, which is located in USA, and hosted Mender, which is located in Europe.

This guide shows how to migrate deployed devices from hosted Mender (USA) to EU hosted Mender (Europe).

Migration to EU hosted Mender is only available in the Mender Enterprise plan. See the Mender features page for an overview of all Mender plans and features. If you wish to migrate your tenant to EU hosted Mender please email contact@mender.io with your request.

Introduction

The migration from one server to the other consists of three steps:

  • From hosted Mender, deploy a software update to your devices which contains an updated mender.conf file. This new configuration will use the Servers property to specify an array of server URLs.
  • Reject devices from the old server, so that the devices fallback to the new server once they get Unauthorized error from the old server.
  • From EU hosted Mender, deploy a new software update with a mender.conf containing only the new server. This step is a formal clean-up and not urgent.

Note that this method will not work on generic instances of the Mender server. It is only possible with hosted Mender and EU hosted Mender because the databases are internally synchronized for users performing the migration.

Step 1: Deploy an update with the new Mender configuration

Prepare the configuration file

The new configuration file must include the Servers field with an array of ServerURL that the device will use. The first element in the array must be the old server (hosted Mender) and the second element must be the new server (EU hosted Mender).

The configuration file cannot include ServerURL field in the root.

Depending on how the original Mender configuration file was generated, this can be achieved in different ways.

For Yocto project integrations, if you are already passing your own configuration file to the build, as described in Customize Mender, modify your mender.conf to include Servers array.

If instead you are relying on meta-mender to autogenerate a configuration file based on variables you need to first capture the currently generated mender.conf, modify it, and use the Customize Mender method to inject it back into the build. The file can be captured from a live device or from yocto tmp/deploy/ directory (which will depend a bit on your setup).

Similarly for Debian family integrations, if you are already passing your own configuration file with a rootfs overlay, modify your mender.conf to include Servers array.

If instead you rely on the autogenerated mender.conf, capture it, modify it, and set it up in a rootfs overlay.

The fields that need modification are:

  • ServerURL shall be set to: "" (empty string)
  • Servers shall be set to: [{ServerURL: "https://hosted.mender.io"}, {ServerURL: "https://eu.hosted.mender.io"}]

You can do this manually with any text editor or using the jq command:

cat mender.conf | jq '
.ServerURL = "" |   # Blank existing ServerURL
.Servers = [        # Set Servers array of ServerURL(s)
  {ServerURL: "https://hosted.mender.io"},
  {ServerURL: "https://eu.hosted.mender.io"}
]' > mender.new.conf

Create the Mender Artifact

Now create an Artifact with the updated mender.conf using the your current workflow to create Artifacts. The Artifact needs to be a full system update.

Upload it to hosted Mender.

Deploy the update

Once the Artifact with the new mender.conf is uploaded to hosted Mender, create a deployment for your fleet with it.

The devices will now be updating their configuration but still using the old hosted Mender (USA) to commit the update and poll for further updates, because they orderly follow the server URLs found in the Servers field of the configuration file.

Step 2: Reject devices from the old server

Once the deployment has successfully finished, the next step is to reject the devices from the old server. As the backend databases have been syncronized, once the devices get an Unauthorized response from the old server they will try with the new server (the next in the Servers array).

To reject devices either use the GUI

reject device

or the API. See API documentation.

Step 3: Update again the Mender configuration

Now it is time to clean-up the configuration file.

The new mender.conf file should contain only the new server in the Servers array:

.Servers = [
  {ServerURL: "https://eu.hosted.mender.io"}
]

Following similar steps that in Step 1 above, create an Artifact with the updated configuration file, upload it to EU hosted Mender, and and deploy it to your devices.

We welcome contributions to improve this documentation. To submit a change, use the Edit link at the top of the page or email us at .