# Upgrade Weka versions ## Upgrade prerequisites Before upgrading your cluster, ensure the following: 1. The backend servers meet the [prerequisites and compatibility](/4.0/support/prerequisites-and-compatibility.md) of the target version. 2. All the backend servers are online. 3. Any rebuild has been completed. 4. There are no outstanding alerts that haven't been addressed. 5. There is at least 4 GB of free space in the `/opt/weka` directory. {% hint style="info" %} **Note:** If you plan a multi-hop version upgrade, once an upgrade is done, a background process of converting metadata to a new format may occur (in some versions). This upgrade takes several minutes to complete before another upgrade can start. You can monitor the progress using the `weka status` CLI command and check if there is a `data upgrade` task in a`RUNNING` state. {% endhint %} {% hint style="warning" %} **Note:** Upgrading a Weka cluster with a server used for more than one of the following protocols, NFS, SMB, or S3, is not recommended.\ Contact the Customer Success Team to ensure only one additional protocol is installed on each server. {% endhint %} ## Supported upgrade paths The Weka upgrade process supports upgrading to higher *minor versions* and *major versions* of the Weka software. When upgrading to a major version, always upgrade to the latest minor version in the new major version. This may require first upgrading to a specific minor version in the current software version, as follows: * To upgrade to Weka software version 4.0.x, go through version 3.14.1 or above * To upgrade to Weka software version 3.14.x, go through version 3.13.1 or above * To upgrade to Weka software version 3.13.x, go through version 3.12.1 or above * To upgrade to Weka software version 3.12.x, go through version 3.11.0 or above * To upgrade to Weka software version 3.11.x, go through version 3.10.0 or above For more information, contact the [Customer Success Team](/4.0/support/getting-support-for-your-weka-system.md#contact-customer-success-team). ## Prepare the cluster for upgrade Download the new release on one of the backends using one of the following methods: * From the backend server, run `weka version get ` where `` is the name of the new version (for example,`4.0.1`), followed by `weka version prepare `. * If you don't have a distribution server set, you can add it explicitly to the command. For example, to get the `4.0.1` version from [get.weka.io](https://get.weka.io/ui/releases/) using a token as follows: ```bash weka version get 4.0.1 --from https://[GET.WEKA.IO-TOKEN]@get.weka.io ``` * From the backend server, run the `curl` command described in the install tab on the [get.weka.io](https://get.weka.io/ui/releases/) new release page. * Download the new version tar file to the backend server and run the `install.sh` command. This method is helpful in environments without connectivity to [get.weka.io](https://get.weka.io), such as dark sites or private VPCs. ## Prepare the backend servers for upgrade (optional) When working with many backend servers, it is possible to prepare the backend servers separately from the upgrade process in advance to minimize the total upgrade time. For a small number of backend servers, this step is not required. The preparation phase prepares all the connected backend servers for the upgrade, which includes downloading the new version and getting it ready to be applied. Once the new version is downloaded to one of the backend servers (as described above), run the following CLI command: `weka local run --in upgrade --prepare-only` ## Upgrade the backend servers Once a new software version is installed on one of the backend servers, upgrade the cluster to the new version by running the following command on the backend server: `weka local run --in upgrade` where `` is the name of the new version (for example,`4.0.1`). The upgrade command skips the download and preparation operations if you already ran the preparation step. You can control the upgrade window time by setting the following parameters in the `upgrade` command: **Parameters**
NameTypeValueLimitationsMandatoryDefault
NameTypeValueLimitationsMandatoryDefault
--stop-io-timeoutStringMaximum time in seconds to wait for IO to stop successfullyNo90s
--host-version-change-timeoutStringMaximum time in seconds to wait for a host version updateNo180s
--disconnect-stateless-clients-timeoutStringMaximum time in seconds to wait for stateless clients to be marked as DOWN and continue the upgrade without themNo60s
--prepare-onlyBooleanDownload and prepare a new software version across all servers in the cluster without performing the actual upgradeNoFalse
--health-check-timeoutStringMaximum time in seconds to wait for the health check to completeNo10s
{% hint style="info" %} **Note:** To run the upgrade command, ensure you are logged in as a Cluster Admin (using a `weka user login`). {% endhint %} Before switching the cluster to the new release, the upgrade command distributes the new release to all cluster servers. It makes the necessary preparations, such as compiling the new `wekafs` driver. If a failure occurs during the preparation, such as the disconnection of a server or failure to build a driver, the upgrade process stops, and a summary message indicates the problematic server. In a successful process, the upgrade stops the cluster IO service, switches all servers to the new release, and then turns the IO service back on. This process takes about 1 minute, depending on the size of the cluster. {% hint style="info" %} **Note:** In large deployments of Weka with many backend servers and hundreds or thousands of clients, it is recommended to adjust the following timeout parameters: * Set `host-version-change-timeout` to `600s` * Set `disconnect-stateless-clients-timeout` to `200s` * Set `health-check-timeout` to `30s` If further assistance and adjustments are required, contact the [Customer Success Team](/4.0/support/getting-support-for-your-weka-system.md#contact-customer-success-team). {% endhint %} ## Upgrade the clients Once all backends are upgraded, the clients remain with the existing version and continue working with the upgraded backends. For a stateless client, once it is rebooted, or a complete `umount` and `mount` is performed, the stateless client is automatically upgraded to the backend version. For stateful clients, a manual upgrade is required, usually during a maintenance window. For a manual upgrade of both stateless or stateful clients, run the following command line on the client: `weka local upgrade` An alert is raised if there is a mismatch between the clients' and the cluster versions. {% hint style="warning" %} For client source versions 4.0.1 and above, add the `--prepare-driver` flag to the command. {% endhint %} {% hint style="info" %} **Note:** Clients with two or more versions behind the version of the backends are not supported. Therefore, clients must be upgraded either automatically or manually before the next software version upgrade. {% endhint %} ## Check the status after the upgrade Once the upgrade is complete, verify that the cluster is in the new version by running the `weka status` command. {% hint style="success" %} **Example:** The following is returned when the system is upgraded to version 4.0.1: `# weka status` \ `Weka v4.0.1` \ `...` {% endhint %} {% hint style="info" %} **Note:** Once the upgrade completes successfully, contact the Customer Success Team to convert the cluster from a single-container Backend (SCB) to a multi-container backend (MCB) architecture. {% endhint %} ## Upgrade revert on failure The disruptiveness of the upgrade procedure is limited to a defined window of 10 minutes. Weka system ensures that either the upgrade process to the new version finishes successfully or the version is automatically reverted to the old one within this window. If a failure occurs, the version is automatically reverted on the backends. In this case, verify that all the backends are reverted to the old version by running the `weka cluster host` command. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.weka.io/4.0/usage/upgrading-weka-versions.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.