Migration from Classic Edition to Standard Edition

With Standard Edition, you can:

• Access to new Instana features, including infrastructure analytics, smart alerts, and custom dashboards, with logging, synthetics, OpenTelemetry, automation, AI agent and LLM observability, and so on
• Manage your deployment by using the stanctl command‑line interface (CLI)
• Scale your environment as monitoring requirements increase
• Select the deployment topology that best meets your needs, including a single‑node system, a three‑node cluster, or a five‑node cluster

Complete the following steps to migrate to Standard Edition. To reduce migration risk, run Classic Edition and Standard Edition in parallel during the transition.

1. Configure Standard Edition with your existing Classic Edition environment.
2. Configure agents to send data to both environments.
3. Validate data collection, configuration, and operational workflows in Standard Edition for two to four weeks.
4. When you are satisfied with the validation results, reconfigure agents to send data only to Standard Edition and deactivate Classic Edition.

You control the migration timeline and can complete the transition when you are confident that the Standard Edition deployment meets your requirements.

Review the sizing requirements for your deployment topology and complete the installation prerequisites before you begin the migration. For more information, see the following topics:

• Standard Edition Standard Edition installation checklist
• Single‑node cluster requirements
• Three‑node cluster requirements
• Five‑node cluster requirements

If you need help with sizing or deployment planning, contact IBM® Support portal or your IBM representative.

You can migrate the tenant unit configuration data from Self-Hosted Classic Edition (Docker). It includes user settings, dashboards, events, alerts, application perspectives, EUM websites, and mobile apps. It also includes additional data.

The following migration paths are supported:

• From Classic Edition to single‑node, three‑node, or five‑node Standard Edition

Complete the following prerequisites:

• Prepare your new host as mentioned in Preparing your single‑node environment or Preparing your multi‑node environment.
  • The Standard Edition requires higher minimum hardware than the base installation because it supports a broader range of features and scalability options. For detailed requirements, see Single‑node requirements.
• Install the stanctl binary. For installation details, see Stanctl installation instructions.
• Ensure that the main release version of the Instana backend on your old host and new host is the same. To check the backend version on Classic Edition, run the following command:

  instana images version

• To determine the corresponding stanctl version for Standard Edition, see the compatibility matrix in the release notes for your Instana version. 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 on the bastion host, transfer the package to the air‑gapped host, install stanctl on the air‑gapped host, and import the package on the air‑gapped host.

To migrate the data, complete the following steps:

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

   • 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.

2. Transfer the dump.tar.gz package from the old host to your new Standard Edition host.

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

   Migration parameters

   Parameter	Usage	Example
   --volume-data=<custom-directory>	Specifies the directory to store configuration and operational data for Elasticsearch, PostgreSQL, and Kafka data stores Default: /mnt/instana/stanctl/data	--volume-data=/custom/data/path
   --volume-metrics=<custom-directory>	Specifies the directory to store metrics and time‑series data for Cassandra and BeeInstana data stores Default: /mnt/instana/stanctl/metrics	--volume-metrics=/custom/metrics/path
   --volume-analytics=<custom-directory>	Specifies the directory to store analytics data for ClickHouse data store Default: /mnt/instana/stanctl/analytics	--volume-analytics=/custom/analytics/path
   --volume-objects=<custom-directory>	Specifies the directory to store object storage data including traces and monitoring data Default: /mnt/instana/stanctl/objects	--volume-objects=/custom/objects/path

   • 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>

   The following dialog is displayed.

   Are you migrating from the Classic offering?

4. Enter "Yes". Single‑domain is retained for all the services.

   After the command, you see the following prompt:

   ? Choose installation type:
    demo <
    production

5. Select production.

   Note:

   Demo installation type is only for test and demo environments. Do not use demo in a production environment.
   When migration is completed successfully, a confirmation message appears, like the following example:

   
      ╭──────────────────────────────────────────────╮ 
      │                                              │ 
      │ Migration completed successfully!            │ 
      │ You can now install Instana Standard Edition. │ 
      │                                              │ 
      ╰──────────────────────────────────────────────╯ 
      

6. 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 Standard Edition in an air‑gapped environment.

   Note:

   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 to configure these settings, including the desired feature flags.

After the installation is successfully completed, a message like 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 Classic Edition environment.

After the migration is complete, if required, you might need to redo some configurations from the old host. You can reconfigure as suggested in the following list to make Standard Edition fully operational.

• A new Standard Edition instance is not connected to any agent by default. Configure your agents to send data to both your old Classic Edition environment and your new Standard Edition environment so you can run both in parallel during validation. 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 for the same events. To prevent 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 to Standard Edition. You must manually enable the feature flags again in your new environment. For more information, see Optional features.

• When you migrate Classic Edition to Standard Edition, all Ingress traffic including the agent, UI, and API traffic is served on a single domain (which is the base domain) by default. To revert this behavior, run the following command after the migration is complete:

  stanctl backend apply \
  --core-use-tu-url-path=false \
  --core-acceptors-agent-host=<desired-agent-acceptor-domain> \
  --core-acceptors-agent-port=<desired-agent-acceptor-port>

When Classic Edition and Standard Edition run simultaneously and both are connected to your agents, the following restrictions apply:

• Agent‑side limitations
  • The Kubernetes sensor in the Instana agent does not support two Instana backend configurations. For a workaround, 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.
• Backend‑side limitations
  • Configuration changes that you make after the migration are not automatically synchronized between the two Instana backends.

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