Upgrade instructions for v5.7.4

Overview

The v5.7.x release includes an upgrade to Keycloak v26.3.0.

Upgrading the cluster is fully automated for all production-scale Hydrolix clusters.

Use the special upgrade instructions only for clusters where

• Keycloak runs on a single node
• The Hydrolix operator is prohibited from running multiple Keycloak pods on that node

For most clusters, use the standard upgrade instructions in the v5.7.4 release notes.

Special upgrade instructions

Use these instructions only for single-node clusters where operator is configured to forbid scheduling multiple Keycloak pods on the same node. This deployment configuration is not unusual for development clusters.

During this upgrade process, the cluster will not be fully usable.

Outline of upgrade steps

1. Scale down keycloak
2. Upgrade: Apply the new Hydrolix operator
3. Scale up keycloak
4. Monitor the upgrade process

Scale down Keycloak

Stop the Keycloak pods.

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

Use your preferred Kubernetes monitoring tool to confirm the keycloak pod terminates and does not restart.

Apply the new Hydrolix operator

Apply the new operator directly with the kubectl command examples below.

GKE

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

EKS

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

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

Scale up Keycloak

Scale Keycloak back up. Replace the replica count with your desired number of pods. If you are using these instructions, it was probably 1.

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

Use your preferred Kubernetes monitoring tool to observe that the keycloak pod restarts.

The init-turbine-api job depends on the new Keycloak to return the cluster to a healthy state.

Monitor the upgrade process

Kubernetes jobs named init-cluster and init-turbine-api will automatically run to upgrade your entire installation to match the new operator's version number. This will take a few minutes, during which time you can observe your pods' restarts with your Kubernetes monitor tool.

Ensure both the init-cluster and init-turbine-api jobs have completed successfully and that the turbine-api pod has restarted without errors. After that, view the UI and use the API of your new installation as a final check.

If the turbine-api pod doesn't restart successfully, or other functionality is missing, check the logs of the init-cluster and init-turbine-api jobs for details about failures. This can be done using the k9s utility or with the kubectl command:

% kubectl logs -l app=init-cluster
% kubectl logs -l app=init-turbine-api

If you need help, contact Hydrolix Support.