Upgrade / Migration of the Helm chart

The Helm Chart of Step is versioned independently of Step itself. This page contains information related to the upgrade of the Helm chart of Step itself. For the upgrade of Step refer to Upgrade / Migration

General migration process

Migration to a newest version of the Chart usually requires nothing more than a Helm upgrade, unless some specific migration tasks are mentioned on that page.

For instance, upgrading from version 0.0.15 to version 1.0.0 would require you to perform the below command (assuming your namespace and instance name is “step”): 

helm --namespace step upgrade -f step.values.yaml step step-1.0.0.tgz

Specific migration tasks

Migration from Chart 1.4.0+ to 1.5.0

Grid Proxy working directory persistence (only if the Grid Proxy is enabled)

Starting with Step 31 and Chart 1.5.0, the Grid Proxy caches the files it downloads from the primary grid, and its working directory can be backed by a PersistentVolumeClaim so that this cache survives pod restarts and rollouts.

Persistence is not enabled by a plain helm upgrade: unless your values file sets gridproxy.persistence.enabled: true (together with gridproxy.persistence.size), no PersistentVolumeClaim is created and the cache stays on the pod’s ephemeral storage, as in previous chart versions. We recommend enabling it when upgrading, see File caching and persistence for the configuration.

Once enabled, the upgrade creates the PersistentVolumeClaim and restarts the Grid Proxy pod to attach it. The cache starts empty and is rebuilt on demand, so no data migration is required, and you do not need to delete the Grid Proxy StatefulSet.

Controller default memory settings

Starting with Chart 1.5.0, the Controller is deployed by default with the environment variable MALLOC_ARENA_MAX=2 and the JVM option -XX:MaxMetaspaceSize=384M. These settings mitigate the JVM native memory fragmentation that could otherwise lead to the Controller container being OOM-killed. They are controlled by two new Helm values, controller.config.MALLOC_ARENA_MAX and controller.config.MAX_METASPACE_SIZE_MB.

These defaults are applied even if the new values are missing from your values file, so the upgrade itself does not require any action. We nevertheless recommend to add them explicitly to your values file when migrating to Chart 1.5.0, so that the Controller memory settings in effect are visible in your own configuration, under your control, and stay stable across future Chart upgrades: 

controller:
  config:
    # [...]
    NON_HEAP_MEMORY_MB: 750
    MALLOC_ARENA_MAX: 2
    MAX_METASPACE_SIZE_MB: 384

Set either value to 0 to disable the corresponding setting. See the Helm Values Configuration for details.

If you previously set these options manually, we recommend to replace them by the new values above: 

controller:
  extraEnvVars:
    - name: MALLOC_ARENA_MAX   # replace with controller.config.MALLOC_ARENA_MAX
      value: "2"
  config:
    JAVA_OPTS: "-XX:MaxMetaspaceSize=384M"   # replace with controller.config.MAX_METASPACE_SIZE_MB

Note that if you keep them, a MALLOC_ARENA_MAX defined in controller.extraEnvVars and a -XX:MaxMetaspaceSize defined in controller.config.JAVA_OPTS take precedence over controller.config.MALLOC_ARENA_MAX and controller.config.MAX_METASPACE_SIZE_MB.

NodeJS agent default version (only if you use NodeJS agents)

Starting with Chart 1.5.0 and Step 31, the default tech.version of the NodeJS agent pool is 24 instead of 20, so the default NodeJS agent image tag is now <step version>-nodejs-24.

If your values file explicitly defines a NodeJS agent pool with tech.version: 20, that pool keeps using the NodeJS 20 agent image after the upgrade. We recommend updating it to 24: 

agent:
  pools:
    - # [...]
      tech:
        type: nodejs
        version: 24

As the NodeJS major version changes, validate your NodeJS keywords (and their npm dependencies) against NodeJS 24 in a non-production environment first.

Migration from Chart 1.2.0+ to 1.3.0

Agent Runtime Image Naming Convention

Starting with Step 29, ALL Step agent runtime images are adopting a new naming convention for improved consistency and maintainability. This affects every agent runtime image, not just the examples shown below.

Examples of changes:

  • Base image: base:21-debian-12-slim → agent/runtime:1.0.0
  • Extended image: browsers:1.0.4-java-21 → agent/runtime-extended:1.0.0
  • Java 25 variants are available as separate images: agent/runtime-java-25:1.0.1 and agent/runtime-extended-java-25:1.0.1

For a complete list of available images, see Agent Runtime Images.

Availability and Chart Defaults:

  • Step 29: New runtime images with the new naming convention become available
  • Chart 1.3.0: Still uses old naming convention by default for backward compatibility
  • Chart 1.4.0 (not yet released): Will use new naming convention by default

Migration Timeline:

  • Step 29: Both old and new image names available (transition period)
  • Step 30+: Old image names deprecated and no longer receive updates

Required Actions:

  1. If you explicitly define agent runtime images in your Helm values:

    • Update all image references to use the new naming convention
    • Test in a non-production environment first
    • Complete migration before upgrading to Step 30

  2. If you use chart defaults:

    • Chart 1.3.0: Continues using old image names - you can migrate at your convenience
    • Chart 1.4.0+: Will automatically use new image names
    • Review your values file to ensure compatibility when upgrading

  3. For detailed instructions, see the Agent Runtime Image Naming Convention Migration Guide

Migration from Chart 1.1.0+ to 1.2.0

Starting from the Chart version 1.2.0, the way Step agents are deployed has been updated in favor of a “binaries copy” mode, allowing the end user to optionally specify the base image he wants to run a Step Agent with. An agent is then deployed as per below:

  • an init container, started from the Agent image, copy the Agent binaries to a shared volume
  • the shared volume is mounted to the main container ( tarted from the base image) under the /home/agent path

For convenience, Exense provides a basic Docker image containing Java 21 and NodeJS 20+ used by default by the Agent main container, as per below: 

docker.exense.ch/step-enterprise/base:21-debian-12-slim

Migrating from Chart 1.0.0 to 1.1.0+

Step Controller migration task

In the Chart version 1.1.0, a new required persistent volume has been added to the Step Controller statefulset in order to ensure the license usage state is correctly persisted.

Therefore, the Controller statefulset needs to be manually deleted prior to executing a Helm upgrade, using below command: 

kubectl -n ${NAMESPACE} delete sts enterprise-controller

Migrating from Chart 0.0.15+ to 1.0.0

There is no migration task required to move from version 0.0.15+ to version 1.0.0.

Migrating from Chart 0.0.14 to 0.0.15+

MongoDB migration task

Chart version higher than 0.0.14 uses Bitnami MongoDB as a sub-chart. As the persistent volume configuration differs, it is required to perform below steps in order to migrate the MongoDB data properly:

  • install the PV Migrate tool on your laptop from https://github.com/utkuozdemir/pv-migrate/tree/master
  • scale down to 0 replica every stateful sets (see https://kubernetes.io/docs/tasks/run-application/scale-stateful-set/)
  • delete the existing MongoDB stateful set (see https://kubernetes.io/docs/tasks/run-application/delete-stateful-set/)
  • perform the Chart upgrade, wait for all pods to be started (wait for the new MongoDB one to stop logging), then scale all stateful sets to 0 replicas once again
  • execute the following command to perform the data migration (ensure to pass proper value for the namespace) : 
    kubectl pv-migrate migrate -n ${NAMESPACE} -N ${NAMESPACE} -P /data/db -d --helm-set rsync.extraArgs="--chown=1001:1001" ${NAMESPACE}-mongodb-data-mongodb-0 datadir-mongodb-0
  • start all components, then verify the data availability
  • delete the old persistent volume claims: 
    kubectl -n ${NAMESPACE} delete pvc ${NAMESPACE}-mongodb-data-mongodb-0
kubectl -n ${NAMESPACE} delete pvc ${NAMESPACE}-mongodb-config-mongodb-0