Categories: ADMIN GUIDE MAINTENANCE

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.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:java-21-debian-12-slim
  • Extended image: browsers:1.0.4-java-21 → agent/runtime-extended:java-21-1.0.4

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

See Also