Downgrade from v5.6.0

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.

Downgrading from v5.6.0 is similar to upgrading to a version of Hydrolix, but with additional steps to roll back the database schema.

The target for downgrading from v5.6.0 should be v5.4.4, which contains forward-compatible table definitions to ensure your Hydrolix installation works correctly after downgrade.

v5.6.0 to v5.4.4 downgrade procedure

Downgrading Hydrolix from v5.6.0 to v5.4.4 is much like upgrading, with a schema migration rollback.

Overview

1. Perform the schema migration rollback
2. Perform the downgrade to v5.4.4

During the upgrade, several schema changes are applied automatically. In order to downgrade, revert these schema changes first using these instructions.

Perform the schema migration rollback

The following steps restore the schema to the schema expected by v5.4.4.

1. Connect to the Kubernetes cluster using k9s and select the namespace holding the Hydrolix cluster.
2. Select the turbine-api pod and turbine-api container.
3. Invoke a shell by entering s.

4. Execute each of the following commands, which will produce STDERR to terminal. Each must exit cleanly.

      ./manage.py migrate projects 0007
      ./manage.py migrate tables 0031
   

5. Exit the k9s utility by pressing Ctrl-C.

Perform the downgrade to v5.4.4

1. Apply the new Hydrolix operator

If you have a self-managed installation, apply the new operator directly with the kubectl command examples below. If you're using Hydrolix-supplied tools to manage your installation, follow the procedure prescribed by those tools.

#### GKE downgrade

=== "GKE downgrade"

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

#### EKS downgrade

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

#### LKE and AKS downgrade

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

1. 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 favorite 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 properly 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 still need help, contact Hydrolix support.