Version specific upgrade instructions

Required manual steps for upgrade to each supported StackState version. Read this before you upgrade!

This page describes StackState v4.4.x.

The StackState 4.4 version range is End of Life (EOL) and no longer supported. We encourage customers still running the 4.4 version range to upgrade to a more recent release.

Go to the documentation for the latest StackState release.

Overview

This page provides specific instructions for upgrading to each currently supported version of StackState. The instructions detail any significant changes that may impact how StackState runs after upgrade, such as a change in memory requirements or configuration.

Review the instructions provided below before you upgrade!

Upgrade instructions

Upgrade to v4.4.x

Kubernetes

v4.4.2

No manual action needed.

v4.4.1

No manual action needed.

v4.4.0

• The CPU and memory requirements to run StackState 4.4 on Kubernetes have been reassessed:

  • The requirements for the recommended highly available setup have grown (from 5) to 6 nodes with 32 GB of memory and 8 vCPUS.

  • The requirements for a minimal highly available setup have grown (from 4) to 5 nodes with 32 GB of memory and 8 vCPUS.

  • A non-high availability setup has been added, the requirements for which are 3 nodes with 32 GB of memory and 8 vCPUS.

• Baselines have been disabled in v4.4. The BaselineFunction and Baseline objects are still available, but they do not serve any purpose other than smooth transition to the Autonomous Anomaly Detector (AAD) framework. If you have custom StackPacks that auto-create baselines, this is the last opportunity to remove baselines from templates and make transition to AAD. In release v4.5 baselines will be removed completely and templates using them will break.

• Transparent propagation has been renamed to Auto propagation. The behavior remains the same.

• The ElasticSearch Helm subchart elasticsearch-exporter has been renamed to prometheus-elasticsearch-exporter. This means that any configuration for that subchart needs to use the new subchart key elasticsearch.prometheus-elasticsearch-exporter.*

• The passwordMd5 field in the file based authentication has been renamed to passwordHash as it is now possible to use bcrypt type passwords.

• Security improvement for Authentication and Authorization. There is a single configuration for groups to roles mappings and a single authentication provider used for both the Base API and Admin API. The default StackState roles are now always available, these could previously be overridden - stackstate-admin, stackstate-power-user, stackstate-guest. Additionally, a new default role stackstate-platform-admin has been introduced.

  stackstate {
    authorization {
      adminGroups = ${stackstate.authorization.adminGroups} ["custom-admin-role-from-ldap-or-oidc-or-keycloak"]
      platformAdminGroups = ${stackstate.authorization.platformAdminGroups} ["custom-platform-admin-role-from-ldap-or-oidc-or-keycloak"]
      powerUserGroups = ${stackstate.authorization.powerUserGroups} ["custom-power-user-role-from-ldap-or-oidc-or-keycloak"]
      guestGroups = ${stackstate.authorization.guestGroups} ["custom-guest-role-from-ldap-or-oidc-or-keycloak"]
    }
  }

  Platform management and platform content management permissions have been separated into two groups - platformAdminGroup and adminGroup. Users in the group platformAdminGroup are limited to only platform management tasks, such as change database retention, clear database, clear caches and view logs. Users in the group adminGroup no longer have platform management permissions.

  How you should proceed with upgrade

  • File based authentication: Use the platformadmin username for platform management instead of admin. The admin user remains functional and has full content management rights as before.

  • External authentication (LDAP/OIDC/Keycloak): An additional role/group should be created in the external authentication system and mapped to the new StackState platformAdmin group.

    stackstate:
      authentication:
        roles:
          ...
          platformAdmin: ["new-external-platform-admin-role"]
          ...

    Users who are assigned this group/role will get platform management permissions. If you wish for one user to manage both the content and the platform, you will still need to configure the external authentication provider with two separate roles/groups and then assign both of those to a single user in the settings of the external authentication system. You should not map the same external role/group to different StackState authorization groups.

  If you are still not sure what you need to do, contact StackState support.

Linux

v4.4.2

No manual action needed.

v4.4.1

No manual action needed.

v4.4.0

• Baselines have been disabled in v4.4. The BaselineFunction and Baseline objects are still available, but they do not serve any purpose other than smooth transition to the Autonomous Anomaly Detector (AAD) framework. If you have custom StackPacks that auto-create baselines, this is the last opportunity to remove baselines from templates and make transition to AAD. In release v4.5 baselines will be removed completely and templates using them will break.

• Transparent propagation has been renamed to Auto propagation. The behavior remains the same.

• Security improvement for Authentication and Authorization. There is a single configuration for groups to roles mappings and a single authentication provider used for both the Base API and Admin API. The default StackState roles are now always available, these could previously be overridden - stackstate-admin, stackstate-power-user, stackstate-guest. Additionally, a new default role stackstate-platform-admin has been introduced.

  stackstate {
    authorization {
      adminGroups = ${stackstate.authorization.adminGroups} ["custom-admin-role-from-ldap-or-oidc-or-keycloak"]
      platformAdminGroups = ${stackstate.authorization.platformAdminGroups} ["custom-platform-admin-role-from-ldap-or-oidc-or-keycloak"]
      powerUserGroups = ${stackstate.authorization.powerUserGroups} ["custom-power-user-role-from-ldap-or-oidc-or-keycloak"]
      guestGroups = ${stackstate.authorization.guestGroups} ["custom-guest-role-from-ldap-or-oidc-or-keycloak"]
    }
  }

  Platform management and platform content management permissions have been separated into two groups - platformAdminGroup and adminGroup. Users in the group platformAdminGroup are limited to only platform management tasks, such as change database retention, clear database, clear caches and view logs. Users in the group adminGroup no longer have platform management permissions.

  How you should proceed with upgrade?

  This impacts you if you have a customized authentication section in the file application_stackstate.conf. If your authentication section has adminGroups, powerUserGroups, guestGroups definitions like in the example below:

  stackstate {
    api {
      authentication {
        ...
        adminGroups = ["your-custom-oidc-or-ldap-or-keycloak-admin-role"]
        powerUserGroups = ["your-custom-oidc-or-ldap-or-keycloak-power-user-role"]
        guestGroups = ["your-custom-oidc-or-ldap-or-keycloak-guest-role"]
        ...
      }
    }
  }

  The subject-role mappings must be moved to a centralized authorization configuration using the syntax xxxGroups = ${stackstate.authorization.xxxGroups} ["custom-role"] as shown in the example below.

  stackstate {
    authorization {
      adminGroups = ${stackstate.authorization.adminGroups} ["your-custom-oidc-or-ldap-or-keycloak-admin-role"]
      platformAdminGroups = ${stackstate.authorization.platformAdminGroups} ["your-custom-oidc-or-ldap-or-keycloak-platform-admin-role"]
      powerUserGroups = ${stackstate.authorization.powerUserGroups} ["your-custom-oidc-or-ldap-or-keycloak-power-user-role"]
      guestGroups = ${stackstate.authorization.guestGroups} ["your-custom-oidc-or-ldap-or-keycloak-guest-role"]
    }
    api {
      authentication {
        ...
        // no subject-role mappings here
        ...
      }
    }
  }

  The list of roles will be extended to include the new, custom roles. The default roles will remain available (stackstate-admin, stackstate-platform-admin, stackstate-guest and stackstate-power-user).

  Provider Specific Instructions

  • File based authentication: Use the platformadmin username for platform management instead of admin. The admin user remains functional and has full content management rights as before.

  • External authentication (LDAP/OIDC/Keycloak): An additional role/group should be created in the external authentication system and mapped to the new StackState platformAdmin group.

    stackstate {
      authorization {
        ...
        platformAdminGroups = ${stackstate.authorization.platformAdminGroups} ["your-custom-oidc-or-ldap-or-keycloak-platform-admin-role"]
        ...
      }
      ...
    }

    Users who are assigned this group/role will get platform management permissions. If you wish for one user to manage both the content and the platform, you will still need to configure the external auth provider with two separate roles/groups and then assign both of those to a single user in the settings of the external auth provider. You should not map the same external role/group to different StackState authorization groups.

  If you are still not sure what you need to do, contact StackState support.

Upgrade to v4.3.x

Kubernetes

v4.3.5

No manual action needed.

v4.3.4

No manual action needed.

v4.3.3

No manual action needed.

v4.3.2

No manual action needed.

v4.3.1

No manual action needed.

v4.3.0

• StackState is tested to run on Kubernetes v1.17, v1.18 and v1.19, or the equivalent OpenShift release (version 4.4, 4.5 or 4.6).

• CPU limits have been added to all pods. If you have customized any of the CPU requests in your values.yaml, you will most likely need to also set the CPU limit for the same pod(s).

• CPU limits and requests have been re-evaluated and increased where needed for stable operation resulting in a change in the number and size of required nodes.

• Two new permissions have been added - manage-event-handlers and execute-restricted-scripts:

  • Guest users will no longer be able to create or edit event handlers.

  • Power Users will no longer be able to execute scripts using the HTTP script API.

  • Admin users will not be affected.

• Baselines have been deprecated and will be removed in v4.4. To reflect this, baseline functions and check functions that use baselines have been renamed. Templates that resolve these functions by name will stop working after upgrade to StackState 4.3. The function identifiers have not changed and can still be used to reference functions, however, it is advised that you migrate to using the Autonomous Anomaly Detector.

• A Slack integration StackPack is now available that includes a new Slack event handler. Existing Slack event handlers will continue to run in StackState v4.3, however, the old Slack event handler has been deprecated and will be removed in a future release of StackState. To continue using Slack event notifications, it is advised to install the Slack StackPack and configure view event handlers to use the new Slack event handler in place of the old Notify via slack for component health state change. (deprecated) and Notify via slack for view health state change.(deprecated).

• Dynatrace StackPack - The location of the Dynatrace check config file has moved. If you choose to upgrade to the version of the Dynatrace StackPack shipped with StackState v4.3, the Agent check configuration file should also be moved. The new location is /etc/sts-agent/conf.d/dynatrace.d/conf.yaml the previous location was /etc/sts-agent/conf.d/dynatrace_topology.d/conf.yaml.

Linux

v4.3.5

No manual action needed.

v4.3.4

No manual action needed.

v4.3.3

No manual action needed.

v4.3.2

No manual action needed.

v4.3.1

No manual action needed.

v4.3.0

• Two new permissions have been added - manage-event-handlers and execute-restricted-scripts:

  • Guest users will no longer be able to create or edit event handlers.

  • Power Users will no longer be able to execute scripts using the HTTP script API.

  • Admin users will not be affected.

• Baselines have been deprecated and will be removed in v4.4. To reflect this, baseline functions and check functions that use baselines have been renamed. Templates that resolve these functions by name will stop working after upgrade to StackState 4.3. The function identifiers have not changed and can still be used to reference functions, however, it is advised that you migrate to using the Autonomous Anomaly Detector.

• A Slack integration StackPack is now available that includes a new Slack event handler. Existing Slack event handlers will continue to run in StackState v4.3, however, the old Slack event handler has been deprecated and will be removed in a future release of StackState. To continue using Slack event notifications, it is advised to install the Slack StackPack and configure view event handlers to use the new Slack event handler in place of the old Notify via slack for component health state change. (deprecated) and Notify via slack for view health state change.(deprecated).

• Dynatrace StackPack - The location of the Dynatrace check config file has moved. If you choose to upgrade to the version of the Dynatrace StackPack shipped with StackState v4.3, the Agent check configuration file should also be moved. The new location is /etc/sts-agent/conf.d/dynatrace.d/conf.yaml the previous location was /etc/sts-agent/conf.d/dynatrace_topology.d/conf.yaml.

Upgrade to v4.2.x

Kubernetes

v4.2.4

No manual action needed.

v4.2.3

Authentication configuration for the Kubernetes Helm chart has been made easier for this release. If your StackState authentication was customized, it will need to be updated. To verify this, check if there is a stackstate.server.config or stackstate.api.config value that contains an authentication section in the values.yaml file(s) used for installation.

Refer to the Authentication configuration documentation to configure the same settings directly in the values.yaml file. After that, the authentication section can be completely removed. If this results in an empty config value it can be removed as well.

v4.2.0

• Node sizing requirements have been increased.

• The old stackstate-server pod has been replaced by a number of separate pods. Custom configuration in values.yaml should be updated:

  • Configured email details in stackstate.components.server.config should be moved to stackstate.components.viewHealth.config.

  • Other custom configuration in stackstate.components.server.config should be moved to stackstate.components.api.config.

• A new mandatory parameter stackstate.baseUrl has been added. This is the public URL of StackState (how StackState is reachable from external machines) and is exposed via the UI script API. The file values.yaml should be updated to include the new stackstate.baseUrl parameter. The old stackstate.receiver.baseUrl parameter has been deprecated and will be removed in a future release, however, when no stackstate.baseUrl is provided in StackState v4.2, the configured stackstate.receiver.baseUrl will be used instead.

Linux

v4.2.4

No manual action needed.

v4.2.3

No manual action needed.

v4.2.0

The following configuration must be manually added after upgrade:

• etc/application_stackstate.conf

  • New mandatory parameter stackstate.web.baseUrl. This is the public URL of StackState (how StackState is reachable from external machines) and is exposed via the UI script API. You can manually create a system environment variable called STACKSTATE_BASE_URL or add the value manually as a string in the file application_stackstate.conf.

The following configuration changes must be manually processed if you are using a customized version of a file:

• etc/stackstate-receiver/application.conf

  • Renamed the namespace stackstate. This is now stackstate.receiver.

  • Renamed the parameter apiKey. This is now named apiKeys and should be a list in the format [${stackstate.receiver.key}, ${?EXTRA_API_KEY}].

• processmanager.conf

  • Added new parameter processes.kafkaToElasticsearch.topology-events.

• processmanager/kafka-topics.conf`

  • Added new section kafka.topics.sts_topology_events.

See also

• How to upgrade a StackPack

• Steps to upgrade StackState

• StackPack versions shipped with each StackState release