OpenShift

Last updated: October 26, 2026

Upgrade instructions for OpenShift-based installations. OpenShift support was introduced in version 4.1.6. See Release Notes for the full changelog.

Upgrade Paths

Click a version to expand upgrade instructions. Orange rows are migration boundaries. All upgrades require helm uninstall before helm upgrade --install because StatefulSets cannot be updated in-place. PVCs/PVs are preserved. Use values.openshift.yaml for arbitrary UID compatibility.

⚠️ 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.openshift.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.openshift.yaml. oc 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.openshift.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.openshift.yaml:


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

Then make sure the namespace’s default ServiceAccount (used by xt-minio) can pull with the registry secret. If you linked the secret during installation, this is already the case:


oc -n xltrail secrets link default xltrail-registry-credentials --for=pull

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.openshift.yaml --version <current-chart-version>
oc -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):
# oc -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.openshift.yaml
# Merge your settings into values.openshift.yaml, including the OIDC values
 
oc config set-context --current --namespace=xltrail
helm uninstall xltrail
oc get pods  # wait until no pods remain
 
helm upgrade --install xltrail xltrail/xltrail -f values.openshift.yaml --version 5.1.0
oc 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.openshift.yaml
# Merge your settings into values.openshift.yaml
 
oc config set-context --current --namespace=xltrail
helm uninstall xltrail
oc get pods  # wait until no pods remain
 
helm upgrade --install xltrail xltrail/xltrail -f values.openshift.yaml --version 5.0.0
oc 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.openshift.yaml
# Merge your settings into values.openshift.yaml
 
oc config set-context --current --namespace=xltrail
helm uninstall xltrail
oc get pods  # wait until no pods remain
 
helm upgrade --install xltrail xltrail/xltrail -f values.openshift.yaml --version 4.3.5166-384943f
oc 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:


oc exec xt-git-web-0 -c git -n xltrail -- df -h /source/repositories
oc 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
oc get pods  # wait until no pods remain
 
helm upgrade --install xltrail xltrail/xltrail -f values.openshift.yaml --version <target> \
  --set maintenanceMode=true --set backupRepositories=true
oc 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.openshift.yaml --version <target> \
  --set maintenanceMode=true --set restoreRepositories=true
oc logs -f xt-app-0 -c ops  # wait until Running

4. Start normally:


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

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


oc 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.openshift.yaml
# Merge your settings into values.openshift.yaml
 
oc config set-context --current --namespace=xltrail
helm uninstall xltrail
oc get pods  # wait until no pods remain
 
helm upgrade --install xltrail xltrail/xltrail -f values.openshift.yaml --version 4.3.4811-3f509cc
oc 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:


oc 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
oc get pods  # wait until no pods remain
 
helm upgrade --install xltrail xltrail/xltrail -f values.openshift.yaml --version 4.2.4548

3. Restore repositories to xt-app-0:


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

4. Verify: oc 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.openshift.yaml
# Merge your settings into values.openshift.yaml
 
oc config set-context --current --namespace=xltrail
helm uninstall xltrail
oc get pods  # wait until no pods remain
 
helm upgrade --install xltrail xltrail/xltrail -f values.openshift.yaml --version 4.2.4548
oc 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.openshift.yaml
# Merge your settings into values.openshift.yaml
 
oc config set-context --current --namespace=xltrail
helm uninstall xltrail
oc get pods  # wait until no pods remain
 
helm upgrade --install xltrail xltrail/xltrail -f values.openshift.yaml --version 4.1.12
oc 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.openshift.yaml
# Merge your settings into values.openshift.yaml
 
oc config set-context --current --namespace=xltrail
helm uninstall xltrail
oc get pods  # wait until no pods remain
 
helm upgrade --install xltrail xltrail/xltrail -f values.openshift.yaml --version 4.1.11
oc 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.openshift.yaml
# Merge your settings into values.openshift.yaml
 
oc config set-context --current --namespace=xltrail
helm uninstall xltrail
oc get pods  # wait until no pods remain
 
helm upgrade --install xltrail xltrail/xltrail -f values.openshift.yaml --version 4.1.10
oc 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.openshift.yaml
# Merge your settings into values.openshift.yaml
 
oc config set-context --current --namespace=xltrail
helm uninstall xltrail
oc get pods  # wait until no pods remain
 
helm upgrade --install xltrail xltrail/xltrail -f values.openshift.yaml --version 4.1.8
oc 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.openshift.yaml
# Merge your settings into values.openshift.yaml
 
oc config set-context --current --namespace=xltrail
helm uninstall xltrail
oc get pods  # wait until no pods remain
 
helm upgrade --install xltrail xltrail/xltrail -f values.openshift.yaml --version 4.1.7
oc get pods  # verify all pods are running

4.1.6 October 9, 2024

First version with OpenShift support. Containers run as non-root user (UID 1001), compatible with OpenShift’s arbitrary UID requirement.


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