Enable automatic upgrades for secured clusters

Stay up-to-date by automating the upgrade process for each secured cluster.

Every release of the StackRox Kubernetes Security Platform includes new features, bug fixes, and enhancements. Beginning from version, you can enable automatic upgrades for all secured clusters and view the upgrade status from the StackRox portal.

Automatic upgrades make it easier to stay up-to-date by automating the manual task of upgrading each secured cluster.

With automatic upgrades, after you upgrade StackRox Central, the StackRox Sensor, Collector, and Compliance services in all secured clusters automatically upgrade to the latest version.

The StackRox Kubernetes Security Platform also enables centralized management of all your secured clusters from within the StackRox portal. The new Clusters view displays information about all your secured clusters, the StackRox Sensor version for every cluster, and upgrade status messages. You can also use this view to selectively upgrade your secured clusters or change their configuration.

  • The StackRox Kubernetes Security Platform version introduces the automatic upgrades feature. You still have to upgrade each secured cluster to at least version using the upgrade instructions. After you upgrade to at least version, you can use automatic upgrades and centralized upgrade management for future releases.
  • The automatic upgrade feature is enabled by default when you upgrade to version See Disable automatic upgrades to disable it.


  • Automatic upgrades for secured clusters is only available for the StackRox Kubernetes Security Platform version and higher.
  • If you are using a private image registry, you must first push the StackRox Sensor and Collector images to your private registry.
  • The Sensor must run with the default RBAC permissions.
  • Automatic upgrades won’t preserve any patches that you’ve made to any StackRox services running in your cluster. However, it preserves all labels and annotations that you have added to any StackRox object.
  • By default, the StackRox Kubernetes Security Platform creates a service account called sensor-upgrader in each secured cluster. This account is highly privileged but is only used during upgrades. If you don’t create this account, you will have to complete future upgrades manually if the Sensor doesn’t have enough permissions.

Enable automatic upgrades

To enable automatic upgrades for all clusters:

  1. Navigate to Platform Configuration > Clusters.
  2. Turn on the Automatically upgrade secured clusters toggle.

This is the default configuration for new installations and upgrades.

Manual upgrades from the Portal

If you don’t want to enable automatic upgrades you can manage your secured cluster upgrades by using the Clusters view. The Clusters view lists all clusters and their upgrade statuses.

Upgrade statusDescription
Up to date with Central versionThe secured cluster is running the same version as StackRox Central. (Shown starting from version 3.0.42.)
On the latest versionThe secured cluster is running the same version as StackRox Central. (Shown in versions before 3.0.42.)
Upgrade availableA new version is available for the StackRox Sensor and Collector.
Upgrade failed. Retry upgrade.The previous automatic upgrade failed. See Automatic upgrade failure for more information.
Manual upgrade requiredThe StackRox Sensor and Collector version is older than version You must manually upgrade your secured clusters as described in the Upgrade StackRox page.
Pre-flight checks completeThe upgrade is in progress. Before performing automatic upgrade, the upgrade installer runs a pre-flight check. During the pre-flight check, the installer verifies if certain conditions are satisfied and then only starts the upgrade process.

To manually trigger upgrades for your secured clusters:

  1. Navigate to Platform Configuration > Clusters.
  2. Select the Upgrade available option under the Upgrade status column for the cluster you want to upgrade.
  3. To upgrade multiple clusters at once, select the checkbox in the Cluster column for the clusters you want to update, and then select Upgrade.

Automatic upgrade failure

Sometimes, the StackRox Kubernetes Security Platform automatic upgrades may fail to install. When an upgrade fails, the status message for the secured cluster changes to Upgrade failed. Retry upgrade. To view more information about the failure and understand why the upgrade failed, select the secured cluster row in the Clusters view.

Some common reasons for the failure are:

  • The sensor-upgrader deployment doesn’t run because of a missing or a non-schedulable image.

  • The pre-flight checks fail, either because of insufficient RBAC permissions because of the cluster state isn’t recognizable. This can happen if you have edited StackRox service configurations or the auto-upgrade.stackrox.io/component label is missing.

  • Errors in executing the upgrade. In this failure event, the upgrade installer automatically attempts to roll back the upgrade.

    Sometimes, the rollback can fail as well. For such cases view the cluster logs to identify the issues or contact StackRox support.

After you identify and fix the root cause for the upgrade failure, you can use the Retry Upgrade to upgrade your secured cluster.

Disable automatic upgrades

To disable automatic upgrades:

  1. Navigate to Platform Configuration > Clusters.
  2. Turn off the Automatically upgrade secured clusters toggle.


We're happy to help! Reach out to us to discuss questions, issues, or feature requests.

© 2021 StackRox Inc. All rights reserved.