Helm

Last updated: October 26, 2026

Upgrade instructions for Helm-based installations (Kubernetes and OpenShift). See Release Notes for the full changelog.

Upgrade Paths

Click a version to expand upgrade instructions. Orange rows are migration boundaries. All Helm upgrades require helm uninstall before helm upgrade --install because StatefulSets cannot be updated in-place. PVCs/PVs are preserved.

⚠️ OIDC-only sign-in — configure your identity provider before upgrading

Version 4.4.0 removes password login, LDAP / Active Directory, password reset and the built-in admin account. Users sign in through your OpenID Connect identity provider (IdP) only. Take a backup first: the migration is irreversible, and you cannot roll back to the previous version without restoring it. If you cannot provide an OIDC identity provider yet, stay on your current release.

1. Register xltrail at your IdP and add the OIDC settings (under xltrail in your values.yaml: oidcIssuerUrl, oidcClientId, oidcClientSecretSecretName, oidcAdminClaim, oidcAdminValue, …; see OIDC settings), see Authentication (OIDC). Without them, xltrail starts but nobody can sign in: the sign-in page shows “Single sign-on is not configured”.

2. Remove the settings that are no longer read: AUTH_PROVIDER, LDAP_*, MAX_INVALID_PASSWORD_ATTEMPTS, PASSWORD_RESET_TOKEN_EXPIRY and ADMIN_API_KEY. Rename ON_KUBERNETES to TLS_TERMINATED_UPSTREAM.

3. Make sure every user who should keep access has an account at the IdP with the same email address as in xltrail. Existing users are linked by verified email (not case sensitive) on first sign-in; set OIDC_TRUST_EMAIL=true if the IdP does not mark emails verified. If no existing user, or more than one, has that email, sign-in creates a new user instead, which takes a seat.

4. Give at least one IdP user the administrator claim (OIDC_ADMIN_CLAIM / OIDC_ADMIN_VALUE). Administrator rights come only from that claim; existing admin flags are not kept.

Chart 5.1.0 also drops the LDAP and password values (authProvider, ldap*, maxInvalidPasswordAttempts, passwordResetTokenExpiry); remove them from your values.yaml. kubectl exec xt-app-0 -c server -- python manage.py users list --admins lists the administrators.

During the upgrade, everyone is signed out, and the built-in admin account, the zoomerdebug support account and users of the old replicated auth provider are deleted. Afterwards, only users linked to the IdP count towards seats. Confirm that a real sign-in works before retiring the previous deployment.

⚠️ MinIO image moved to the GitLab registry (charts <= 5.0.0)

docker.io/minio/minio no longer exists on Docker Hub, so pod xt-minio-0 fails to pull its image. MinIO now comes from the private registry registry.gitlab.com/xltrail/xltrail/minio:RELEASE.2023-10-16T04-13-43Z.

Charts after 5.0.0 (e.g. 5.1.0) need no manual step: the image defaults to the GitLab registry and the MinIO StatefulSet carries imagePullSecrets from global.registryCredentialsSecretName (default xltrail-registry-credentials). If your values.yaml overrides the minio image, point it at the GitLab registry as below.

Existing installations that stay on a chart up to and including 5.0.0 need a one-time manual step, because these charts render no imagePullSecrets on the MinIO StatefulSet. Point the MinIO image at the GitLab registry in your values.yaml:


minio:
  imageRegistry: registry.gitlab.com
  imageRepository: xltrail/xltrail/minio
  imageTag: RELEASE.2023-10-16T04-13-43Z

Then give the namespace’s default ServiceAccount (used by xt-minio) the registry pull secret. The xltrail-registry-credentials docker-registry secret already exists in the namespace. Patching the ServiceAccount rather than the StatefulSet survives helm upgrade, as the chart does not manage the default ServiceAccount:


kubectl -n xltrail patch serviceaccount default \
  -p '{"imagePullSecrets":[{"name":"xltrail-registry-credentials"}]}'

Apply the new image with a Helm upgrade on your current chart version (the StatefulSet keeps the old image until then), and watch the pod come back:


helm list -n xltrail  # note your current chart version
helm upgrade xltrail xltrail/xltrail -n xltrail -f values.yaml --version <current-chart-version>
kubectl -n xltrail get pod xt-minio-0 -w
# Only if xt-minio-0 is still in ImagePullBackOff (a pod that never became ready can block the rollout):
# kubectl -n xltrail delete pod xt-minio-0

5.1.0 latest October 26, 2026


helm repo add xltrail https://xltrail.com/charts
helm repo update
helm show values xltrail/xltrail --version 5.1.0 > values.yaml
# Merge your settings into values.yaml, including the OIDC values
 
kubectl config set-context --current --namespace=xltrail
helm uninstall xltrail
kubectl get pods  # wait until no pods remain
 
helm upgrade --install xltrail xltrail/xltrail -f values.yaml --version 5.1.0
kubectl get pods  # verify all pods are running

5.0.0 May 28, 2026


helm repo add xltrail https://xltrail.com/charts
helm repo update
helm show values xltrail/xltrail > values.yaml
# Merge your settings into values.yaml
 
kubectl config set-context --current --namespace=xltrail
helm uninstall xltrail
kubectl get pods  # wait until no pods remain
 
helm upgrade --install xltrail xltrail/xltrail -f values.yaml --version 5.0.0
kubectl get pods  # verify all pods are running

4.3.5166-384943f December 11, 2025


helm repo add xltrail https://xltrail.com/charts
helm repo update
helm show values xltrail/xltrail > values.yaml
# Merge your settings into values.yaml
 
kubectl config set-context --current --namespace=xltrail
helm uninstall xltrail
kubectl get pods  # wait until no pods remain
 
helm upgrade --install xltrail xltrail/xltrail -f values.yaml --version 4.3.5166-384943f
kubectl get pods  # verify all pods are running

⚠️ PVC migration — MinIO backup/restore required

Version 4.3.4811 introduces a new PVC xt-git-repositories which replaces the old xt-source-xltrail-volume-xt-git-web-0. Migration uses MinIO as temporary storage.

1. Snapshot the PVC xt-source-xltrail-volume-xt-git-web-0 for backup. Ensure the MinIO PVC has enough space:


kubectl exec xt-git-web-0 -c git -n xltrail -- df -h /source/repositories
kubectl exec xt-minio-0 -n xltrail -- df -h /data

2. Uninstall, then run in backup mode (copies repos from old PVC to MinIO):


helm uninstall xltrail
kubectl get pods  # wait until no pods remain
 
helm upgrade --install xltrail xltrail/xltrail -f values.yaml --version <target> \
  --set maintenanceMode=true --set backupRepositories=true
kubectl logs -f xt-git-web-0 -c ops  # wait until Running

3. Run in restore mode (copies repos from MinIO to new PVC):


helm upgrade --install xltrail xltrail/xltrail -f values.yaml --version <target> \
  --set maintenanceMode=true --set restoreRepositories=true
kubectl logs -f xt-app-0 -c ops  # wait until Running

4. Start normally:


helm upgrade --install xltrail xltrail/xltrail -f values.yaml --version <target>

5. Verify everything works, then delete the old PVC:


kubectl delete pvc xt-source-xltrail-volume-xt-git-web-0

4.3.4811-3f509cc July 4, 2025


helm repo add xltrail https://xltrail.com/charts
helm repo update
helm show values xltrail/xltrail > values.yaml
# Merge your settings into values.yaml
 
kubectl config set-context --current --namespace=xltrail
helm uninstall xltrail
kubectl get pods  # wait until no pods remain
 
helm upgrade --install xltrail xltrail/xltrail -f values.yaml --version 4.3.4811-3f509cc
kubectl get pods  # verify all pods are running

⚠️ StatefulSet migration — xt-git-web → xt-app

Version 4.2.4548 renamed the StatefulSet from xt-git-web to xt-app. This requires a manual backup and restore of git repositories via MinIO.

1. Backup repositories from xt-git-web-0:


kubectl exec xt-git-web-0 -c git -n xltrail -- \
  mc cp --recursive /source/repositories/ minio/xltrail-repositories/

2. Uninstall and deploy the new version (creates xt-app StatefulSet):


helm uninstall xltrail
kubectl get pods  # wait until no pods remain
 
helm upgrade --install xltrail xltrail/xltrail -f values.yaml --version 4.2.4548

3. Restore repositories to xt-app-0:


kubectl exec xt-app-0 -c git -n xltrail -- \
  mc cp --recursive minio/xltrail-repositories/ /source/repositories/

4. Verify: kubectl get pods — everything should be up and running.

4.2.4548 April 28, 2025


helm repo add xltrail https://xltrail.com/charts
helm repo update
helm show values xltrail/xltrail > values.yaml
# Merge your settings into values.yaml
 
kubectl config set-context --current --namespace=xltrail
helm uninstall xltrail
kubectl get pods  # wait until no pods remain
 
helm upgrade --install xltrail xltrail/xltrail -f values.yaml --version 4.2.4548
kubectl get pods  # verify all pods are running

4.1.12 March 18, 2025


helm repo add xltrail https://xltrail.com/charts
helm repo update
helm show values xltrail/xltrail > values.yaml
# Merge your settings into values.yaml
 
kubectl config set-context --current --namespace=xltrail
helm uninstall xltrail
kubectl get pods  # wait until no pods remain
 
helm upgrade --install xltrail xltrail/xltrail -f values.yaml --version 4.1.12
kubectl get pods  # verify all pods are running

4.1.11 March 9, 2025


helm repo add xltrail https://xltrail.com/charts
helm repo update
helm show values xltrail/xltrail > values.yaml
# Merge your settings into values.yaml
 
kubectl config set-context --current --namespace=xltrail
helm uninstall xltrail
kubectl get pods  # wait until no pods remain
 
helm upgrade --install xltrail xltrail/xltrail -f values.yaml --version 4.1.11
kubectl get pods  # verify all pods are running

4.1.10 February 13, 2025


helm repo add xltrail https://xltrail.com/charts
helm repo update
helm show values xltrail/xltrail > values.yaml
# Merge your settings into values.yaml
 
kubectl config set-context --current --namespace=xltrail
helm uninstall xltrail
kubectl get pods  # wait until no pods remain
 
helm upgrade --install xltrail xltrail/xltrail -f values.yaml --version 4.1.10
kubectl get pods  # verify all pods are running

4.1.8 January 31, 2025


helm repo add xltrail https://xltrail.com/charts
helm repo update
helm show values xltrail/xltrail > values.yaml
# Merge your settings into values.yaml
 
kubectl config set-context --current --namespace=xltrail
helm uninstall xltrail
kubectl get pods  # wait until no pods remain
 
helm upgrade --install xltrail xltrail/xltrail -f values.yaml --version 4.1.8
kubectl get pods  # verify all pods are running

4.1.7 October 30, 2024


helm repo add xltrail https://xltrail.com/charts
helm repo update
helm show values xltrail/xltrail > values.yaml
# Merge your settings into values.yaml
 
kubectl config set-context --current --namespace=xltrail
helm uninstall xltrail
kubectl get pods  # wait until no pods remain
 
helm upgrade --install xltrail xltrail/xltrail -f values.yaml --version 4.1.7
kubectl get pods  # verify all pods are running

4.1.6 October 9, 2024


helm repo add xltrail https://xltrail.com/charts
helm repo update
helm show values xltrail/xltrail > values.yaml
# Merge your settings into values.yaml
 
kubectl config set-context --current --namespace=xltrail
helm uninstall xltrail
kubectl get pods  # wait until no pods remain
 
helm upgrade --install xltrail xltrail/xltrail -f values.yaml --version 4.1.6
kubectl get pods  # verify all pods are running

⚠️ Non-root migration — fsGroup / chown required

Since 4.1.6, all containers run as non-root user (UID 1001). When upgrading from < 4.1.6, existing files under /source/repositories may be owned by root.

The chart handles this automatically via an init container controlled by git.provisionMountPath (default: true). If your cluster does not allow init containers to run as root, run a one-off pod:


kubectl run chown-repositories -n xltrail \
  --image=alpine --restart=Never \
  --overrides='{"spec":{"securityContext":{"runAsUser":0},"containers":[{"name":"chown-repositories","image":"alpine","command":["chown","-R","1001:0","/source/repositories"],"volumeMounts":[{"name":"source","mountPath":"/source/repositories"}]}],"volumes":[{"name":"source","persistentVolumeClaim":{"claimName":"xt-source-xltrail-volume-xt-git-web-0"}}]}}'
kubectl wait pod chown-repositories -n xltrail \
  --for=jsonpath='{.status.phase}'=Succeeded --timeout=5m
kubectl delete pod chown-repositories -n xltrail

Then continue with the standard upgrade for your target version.

Symptom of incorrect ownership: Sync error: repository path '/source/repositories/<repo-id>/origin/' is not owned by current user

4.1.5 September 22, 2024


helm repo add xltrail https://xltrail.com/charts
helm repo update
helm show values xltrail/xltrail > values.yaml
# Merge your settings into values.yaml
 
kubectl config set-context --current --namespace=xltrail
helm uninstall xltrail
kubectl get pods  # wait until no pods remain
 
helm upgrade --install xltrail xltrail/xltrail -f values.yaml --version 4.1.5
kubectl get pods  # verify all pods are running

4.1.4 September 13, 2024


helm repo add xltrail https://xltrail.com/charts
helm repo update
helm show values xltrail/xltrail > values.yaml
# Merge your settings into values.yaml
 
kubectl config set-context --current --namespace=xltrail
helm uninstall xltrail
kubectl get pods  # wait until no pods remain
 
helm upgrade --install xltrail xltrail/xltrail -f values.yaml --version 4.1.4
kubectl get pods  # verify all pods are running

4.1.3 July 26, 2024


helm repo add xltrail https://xltrail.com/charts
helm repo update
helm show values xltrail/xltrail > values.yaml
# Merge your settings into values.yaml
 
kubectl config set-context --current --namespace=xltrail
helm uninstall xltrail
kubectl get pods  # wait until no pods remain
 
helm upgrade --install xltrail xltrail/xltrail -f values.yaml --version 4.1.3
kubectl get pods  # verify all pods are running

4.1 July 18, 2024


helm repo add xltrail https://xltrail.com/charts
helm repo update
helm show values xltrail/xltrail > values.yaml
# Merge your settings into values.yaml
 
kubectl config set-context --current --namespace=xltrail
helm uninstall xltrail
kubectl get pods  # wait until no pods remain
 
helm upgrade --install xltrail xltrail/xltrail -f values.yaml --version 4.1
kubectl get pods  # verify all pods are running

⚠️ v4.0 upgrade — PVC resize + reprocessing

Upgrading to v4.0 triggers reprocessing of all repositories (may take hours). The xltrail PVC must be resized to match the git PVC.

1. Snapshot PVC xt-source-xltrail-volume-xt-git-web-0 for backup.

2. Uninstall and resize PVC:


kubectl config set-context --current --namespace=xltrail
helm uninstall xltrail
kubectl get pods  # wait until no pods remain
 
kubectl patch pvc xt-source-xltrail-volume-xt-git-web-0 \
  -p '{ "spec": { "resources": { "requests": { "storage": "100Gi" }}}}'
kubectl get pvc  # verify size

3. Install the latest version:


helm upgrade --install xltrail xltrail/xltrail -f values.yaml

4. Migrate drag-and-drop projects (once pods are running):


kubectl exec -it svc/xt-web -c server -- python /server/scripts/k8s_repo_migration.py

Note: Reprocessing may take up to a few hours.

5. Clean up old PVCs (once everything works):


kubectl delete pvc/xt-filestore-volume-xt-filestore-0
kubectl delete pvc/xt-source-git-volume-xt-git-web-0

3.5.0

Update the imageTag under minio in your values.yaml:


imageTag: RELEASE.2021-12-10T23-03-39Z

Then follow the standard upgrade steps.