Legacy single machine migration guide

Migrate from legacy single machine to single node cluster.


To get started with your migration from a legacy single machine instance to a single node cluster, you’ll need the following things prepared in advance:

  • Running the latest legacy single machine version (v3.2310.1)
  • Backup of the single machine instance
  • Ensure the system requirements are met for the instance to be migrated
    • Additionally, the migration will require an extra 100GB of disk space for the migration process
  • Ruby 2.7 or higher on the instance to be migrated
  • Have the following tools available on the instance: curl, tar, jq
  • License key for the single node cluster, contact us for a license key

Migration Overview

The migration process is handled by a script which will perform the following steps:

  1. Migrating the configuration - Converts the configuration on the legacy single machine instance to the single node cluster version.

  2. Stopping the legacy single machine installation - Stops the legacy single machine instance to prevent any new data being written to the instance.

  3. Install kURL - Installs kURL on the instance to be migrated. This will also remove Docker from the instance.

  4. Install single node cluster - Installs the single node cluster on the instance to be migrated.

  5. Scale down Apps and Databases - Scales down the apps and databases on the single node cluster to allow for the migration of data.

  6. Remove data from single node cluster - Removes any data that was created during the installation of the single node cluster. This does not remove any data from the legacy single machine instance.

  7. Migrate data - Moves data from the legacy single machine location to the single node cluster location.

  8. Scale up Apps and Databases - Scales up the apps and databases on the single node cluster.

Ensure that you have made a backup of the single machine instance before starting the migration.

Running the migration

The time taken by the migration will be dependent on the amount of data used by the single machine instance. We estimate that it takes around 15-30 mins to complete the migration during which time there will be downtime and no events will be received or processed by BugSnag.

Download the required files

Download scripts required for the migration:

curl -sSL -o migrate-settings.rb https://s3.amazonaws.com/bugsnag-onprem-public/migration/latest/migrate-settings.rb
curl -sSL -o single-machine-migration.sh https://s3.amazonaws.com/bugsnag-onprem-public/migration/latest/single-machine-migration.sh

Run the migration

Ensure that both the migration and configuration scripts are in the same directory. Run the following command to start the migration:

sudo bash single-machine-migration.sh --bugsnag-data-dir <path-to-bugsnag-data-directory>

You can also provide the following flags to the migration script:

Flag Type Description
--bugsnag-data-dir string Required. Path to the single machine data directory. You can find this via the replicated admin console in settings under Data directory or by running replicatedctl app-config export --hidden --template '{{.BUGSNAG_DATA_DIR.Value}}'
string Path to the airgap bundle
string Path to the license file, defaults to license.yaml in current directory
string Path to the config file, defaults to config.yaml in current directory. Only required if config has already been migrated
--kurl-airgap-bundle-path string Path to store the kURL airgap bundle, defaults to /tmp/kurl_install.tar.gz
--kurl-airgap-extracted-dir string Path to store the extracted kURL airgap bundle, defaults to /tmp/kurl_install

If the script is interrupted or fails, it will continue from the incomplete step. If you need to restart the migration, you can run the migration script again. Please contact us if you encounter any issues during the migration along with the logs from the migration script.

Once the migration has been completed and the single node cluster is running, you will need to update your DNS to route traffic to the updated endpoints.

Post-migration steps

Update routing

The following table shows the changes to the ports after the migration:

Legacy single machine Single node cluster Description
49080 30080 Dashboard
49000 30000 Event Server
49003 30003 Sessions Server
49001 30001 Upload Server
49002 30002 Hooks Server
49004 30004 Build API
49080 30080 Data Access API
49300 30300 Grafana