Upgrading Instana backend on Kubernetes/OpenShift

To upgrade the operator-based Instana setup, follow these steps:

Upgrade procedure
Upgrade notes

Upgrade procedure

The upgrade policy provides that at most one release can be skipped, that is, it's possible to upgrade from release 245-x to release 247-x or release 249-x, but no further. If the policy does not allow you to do the required upgrade in one go, then you need to carry out more than one upgrade step.

Install the target version of Instana kubectl plug-in. For more information, see Installing the Instana kubectl plug-in.
Upgrade the operator by using either of the following methods:
- Applying Manifests directly
- Rendering Manifests only
Notes:
- Ensure that you apply or generate new YAML manifests. Don't update the image version in the existing YAML manifests directly. If you update the image version in the existing YAML manifests, then you might miss the CustomResourceDefinition (CRD) updates or other changes that can lead to unpredictable errors.
- To upgrade to a specific version, you might require to do some extra actions. Refer to the Upgrade notes section. When you skip a release, ensure that you consider the upgrade notes (including upgrade notes for the skipped version and the target version).
Verify the Instana backend upgrade by doing the following steps:
- Check whether the Instana kubectl plug-in version is updated by running the kubectl instana -version command.
- Check whether the Instana backend version is updated by running the kubectl get core -n instana-core and kubectl get units -n instana-units commands.

Upgrade notes

Upgrading to release 249

A new Artifactory server is now used as Docker registry. You must update the image pull secrets. For more information, see the following topics:

Upgrading to release 247

If single-host data stores were set up by using instana-console, data store authentication must be enabled from release 247 on. In this case, an update to 247 is done in the following two steps:

On the single-host data store host, install instana-console 247 or later, and then add the required credentials into the db-setttings.hcl file. The simplest way to do this is to run the instana datastores settings Instana CLI command. This command creates a db-settings.hcl file that contains the required credentials. Then, run the instana datastores update -f /path/to/db-settings.hcl command to perform the update.

Make adjustments to the Operator side. The data store configurations in the Core custom resource must be adjusted, and the corresponding credentials need to be transferred from the data store host to the Core secret. Add the following data with the customized passwords from the db-settings.hcl file to the config.yaml file entry of the Core Secret:

apiVersion: v1
metadata:
  name: instana-core
  namespace: instana-core
type: Opaque
stringData:
  config.yaml: |
    ...
    datastoreConfigs:
      beeInstanaConfig:
        user: aggregator
        password: <password>
      clickhouseConfigs:
        - adminUser: clickhouse
          adminPassword: <password>
          user: clickhouse
          password: <password>
      cassandraConfigs:
        - adminUser: cassandra
          adminPassword: <password>
          user: cassandra
          password: <password>
      postgresConfigs:
        - adminUser: postgres
          adminPassword: <password>
          user: postgres
          password: <password>
      elasticsearchConfig:
        adminUser: elastic
        adminPassword: <password>
        user: elastic
        password: <password>
      kafkaConfig:
        adminUser: kafka
        adminPassword: <password>
        consumerUser: kafka
        consumerPassword: <password>
        producerUser: kafka
        producerPassword: <password>
...

Enable data store authentication in the Core custom resource as follows:

apiVersion: instana.io/v1beta2
kind: Core
metadata:
  name: instana-core
  namespace: instana-core
spec:
  ...
  datastoreConfigs:
    beeInstanaConfig:
      authEnabled: true
      hosts:
        - <dbhost>
    cassandraConfigs:
      - authEnabled: true
        hosts:
          - <dbhost>
    clickhouseConfigs:
      - authEnabled: true
        clusterName: local
        hosts:
          - <dbhost>
    elasticsearchConfig:
      authEnabled: true
      clusterName: onprem_onprem
      hosts:
        - <dbhost>
    kafkaConfig:
      authEnabled: true
      hosts:
        - <dbhost>
    postgresConfigs:
      - authEnabled: true
        hosts:
          - <dbhost>

Upgrading to release 245

This release requires at least Kubernetes 1.22 or Red Hat OpenShift 4.9.

If you are upgrading from release 241-x, make sure you perform the migration to PostgreSQL as described in the upgrading section for release 243.

Upgrading to release 243

The operator now uses PostgreSQL instead of CockroachDB and the data needs to be migrated from CockroachDB to PostgreSQL.

If you're using single-host data store setup, then follow these steps:

Update the data stores by using the following command in the instana-console. This command updates the existing data store containers and runs a new PostgresSQL container.
```
instana datastores update
```

The data migration from CockroachDB to PostgreSQL will start automatically after you configure postgresConfigs in the spec for the Core.

spec:
  datastoreConfigs:
    postgresConfigs:
       - hosts:
            - <PostgreSQL Server Address>

After the migration, remove datastoreConfigs.cockroachdbConfig configuration from the spec of the Core.
Finish the migration by running below command. It disables CockroachDB support after PostgreSQL migration and stops the CockroachDB container.
```
instana datastores pg-migrated
```

For any other data store setup, follow these steps:

Set up a PostgreSQL 15.x server or cluster.
The data migration from CockroachDB to PostgreSQL will start automatically after you configure postgresConfigs in the spec for the Core. The Instana operator will log an error if postgresConfigs are not configured.
```
spec:
  datastoreConfigs:
    postgresConfigs:
      - hosts:
          - <PostgreSQL Server Address>
```
After the migration, remove datastoreConfigs.cockroachdbConfig configuration from the spec of the Core.