Upgrading Instana backend on Kubernetes/OpenShift

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

Upgrade procedure

The upgrade policy provides that at most one release can be skipped, that is, it's possible to upgrade from release 247-x to release 249-x or release 251-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.

  1. Install the target version of Instana kubectl plug-in. For more information, see Installing the Instana kubectl plug-in.

  2. Upgrade the operator by using either of the following methods:

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

  3. 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 251

No special steps are needed.

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:

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

  2. 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: elastics
        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>