Migrating from Self-Hosted Classic Edition (Docker) or Standard Edition to Standard Edition

Prerequisites

You cannot migrate your Classic Edition data to a host on which Standard Edition is already installed. You must use a new host.

Complete the following prerequisites:

• Prepare your new host as mentioned in Preparing your single-node environment or Preparing your multi-node environment.
  • For DNS settings, use the tenant and unit names of your old environment. Since the tenant and unit names are part of the unit domain name, these names must be present in the DNS record of the Standard Edition environment. This is also necessary for logging in to Standard Edition by using LDAP authentication, as LDAP configurations are also migrated.
• Install the stanctl binary. For more information, see Installing stanctl command-line tool.
• Ensure that the Instana backend version of your old host and new host is the same. If required, upgrade the backend:
  • To upgrade the Instana backend on Classic Edition, see Upgrading Classic Edition. The Instana backend on Classic Edition must be build 271 or later.
  • To upgrade the Instana backend on Standard Edition, see Upgrading Standard Edition.
• For air-gapped migration, create an air-gapped package and transfer the package to your Standard Edition air-gapped host.

Migrating to Standard Edition

To migrate the data, complete the following steps:

1. Extract the tenant unit configuration data from the Postgres data store.

   • If you are migrating from Classic Edition, run the following command on the Classic Edition host:

     instana dump config-data
     

   A dump.tar.gz file is created in the ./dump directory. This file contains the tenant unit configuration data in the form of executable SQL queries.

   • If you are migrating from Standard Edition, run the following command on the old Standard Edition host:

     stanctl dump config-data
     

   A dump-<timestamp>.tar.gz file is created in the current directory. This file contains the tenant unit configuration data in the form of executable SQL queries.

2. Do one of the following steps:

   • Online migration: Transfer the dump tar.gz package from the old host to your new Standard Edition host.
   • Air-gapped migration: Transfer the dump tar.gz package from the old host to your new Standard Edition air-gapped host by using the bastion host.

3. On your new Standard Edition host, migrate the data from the tar.gz file.

   • For a single-node deployment, run the following commands:
     • Online migration

       stanctl migrate -f </path/to/tar.gz>
       

     • Air-gapped migration

       stanctl migrate --air-gapped -f </path/to/tar.gz>
       

   • For a multi-node deployment, run the following commands:
     • Online migration

       stanctl migrate --file=</path/to/tar.gz> --multi-node-enable --multi-node-ips=<node0IPaddress,node1IPaddress,node2IPaddress>
       

     • Air-gapped migration

       stanctl migrate --air-gapped --file=</path/to/tar.gz> --multi-node-enable --multi-node-ips=<node0IPaddress,node1IPaddress,node2IPaddress>
       

   After you run the command, you see the following prompt:

   ? Choose installation type:
   demo <
   production
   

4. Choose your preferred installation type. For multi-node clusters, only the production installation type is supported.

5. Install Standard Edition with the tenant unit configuration data that you migrated from your old host. For more information, see Installing the Standard Edition in an online environment or Installing the Standard Edition in an air-gapped environment.

   If you want to configure additional settings such as custom certificates, SMTP configuration, proxies, and other settings, see Instana backend configurations. You can use the configuration flags with the stanctl up command.

After the installation is successfully completed, a message similar to the following example is displayed:

****************************************************************
* Successfully installed Instana Self-Hosted Standard Edition! *
*                                                              *
* URL: https://instana.example.com                             *
* Username: admin@instana.local                                *
****************************************************************

You can sign in to the new Standard Edition UI by using the same tenant password that you used in your old setup.

Post-migration configurations

If required, you might need to redo some configurations that were on the old host. You can reconfigure as suggested in the following list:

• New Standard Edition instance is not connected to any agent by default. To connect your agents to the old and new backends, see Configuring multiple backends.

• After the migration, when the old and new environments are connected to your agents, both the Instana environments generate alerts. To avoid duplicate alerts, you can set a maintenance window on one of your Instana instances. For more information, see Scheduling maintenance windows.

• Feature flags that were enabled in your old environment are not migrated. You must manually enable the feature flags again in your new environment. For more information, see Optional features.

Limitations

The following restrictions are applicable for simultaneous reporting into two Instana backends:

• The Kubernetes sensor in the Instana agent does not support two Instana backend configurations. See Report to multiple backends for Kubernetes monitoring.
• The EUM (end-user monitoring) clients do not support reporting to two Instana backends.
• Serverless client implementations do not support reporting to two Instana backends.
• Configuration changes made after the migration are not automatically synchronized between the two Instana backends.

Troubleshooting

You might encounter issues after migration. If you are unable to resolve these issues, contact IBM Support.

STANCTL_UNIT_INITIAL_ADMIN_PASSWORD=instana1