Skip to content

Upgrade to v5.7.4

Do not skip versions when upgrading or downgrading

Skipping versions when upgrading or downgrading Hydrolix can result in database schema inconsistencies and cluster instability. Always upgrade or downgrade sequentially through each version.

Overview⚓︎

The v5.7.x release introduces an upgrade to Keycloak v26.3.0. For most production-scale Hydrolix clusters, the upgrade process is fully automated. However, special procedures apply to specific deployment configurations.

Special upgrade instructions are required only when:

  • Keycloak operates on a single node
  • The Hydrolix operator cannot schedule multiple Keycloak pods on that node

These conditions typically characterize development environments. Standard upgrade procedures appear in the v5.7.4 release notes for other deployments.

Special upgrade instructions⚓︎

These steps apply exclusively to single-node clusters with operator scheduling restrictions preventing multiple Keycloak pods. During this process, cluster functionality will be limited.

Upgrade steps overview⚓︎

The process follows four phases:

  1. Scale down Keycloak
  2. Apply the new Hydrolix operator
  3. Scale up Keycloak
  4. Monitor the upgrade

Phase 1: Scale down Keycloak⚓︎

Execute this command to terminate Keycloak pods:

1
kubectl scale deployment -n "${HDX_KUBERNETES_NAMESPACE}" keycloak --replicas=0

Verify pod termination and that it does not automatically restart using your Kubernetes monitoring tool.

Phase 2: Apply new operator⚓︎

Select the appropriate command based on your cloud provider:

GKE:

1
kubectl apply -f "https://www.hydrolix.io/operator/v5.7.4/operator-resources?namespace=${HDX_KUBERNETES_NAMESPACE}&gcp-storage-sa=${GCP_STORAGE_SA}"

EKS:

1
kubectl apply -f "https://www.hydrolix.io/operator/v5.7.4/operator-resources?namespace=${HDX_KUBERNETES_NAMESPACE}&aws-storage-role=${AWS_STORAGE_ROLE}"

LKE and AKS:

1
kubectl apply -f "https://www.hydrolix.io/operator/v5.7.4/operator-resources?namespace=${HDX_KUBERNETES_NAMESPACE}"

Phase 3: Scale up Keycloak⚓︎

Restore Keycloak pods using this command (adjust replicas to match your deployment):

1
kubectl scale deployment -n "${HDX_KUBERNETES_NAMESPACE}" keycloak --replicas=1

Confirm pod restart through your Kubernetes monitoring interface.

Phase 4: Monitor upgrade progress⚓︎

Automated jobs named init-cluster and init-turbine-api execute to synchronize your installation with the new operator version. This typically requires several minutes. Monitor pod restarts using your preferred Kubernetes tool.

Verify successful completion by confirming both jobs finished without errors and the turbine-api pod restarted successfully. Access the UI and test API functionality as final validation.

Troubleshooting: If turbine-api fails to restart or functionality is compromised, examine job logs:

1
2
kubectl logs -l app=init-cluster
kubectl logs -l app=init-turbine-api

Contact Hydrolix Support at support@hydrolix.io for additional assistance.