---
title: "Weaviate 1.25 migration guide for Kubernetes users"
description: "Assumptions & requirements"
url: https://docs.weaviate.io/deploy/migration/weaviate-1-25
---

# Weaviate 1.25 migration guide for Kubernetes users

## Assumptions & requirements

This migration guide assumes that you have:

- A working knowledge of kubernetes, helm and shell commands.
- Deployed Weaviate on kubernetes, in the `weaviate` namespace
- Access to your helm configuration file e.g. (`values.yaml`).

## Migration overview

Weaviate `1.25` introduces [Raft](https://raft.github.io/) as the consensus algorithm for its cluster metadata, in order to improve its fault tolerance. This change requires a migration of the entire metadata.

> [!TIP]
>
> **cluster metadata and schema**
>
> The cluster metadata was previously referred to as the `schema`. We now use the term `metadata`, and use `schema` to refer to the data model of the Weaviate instance, such as classes, properties, etc.

As a result, to migrate from a pre-`1.25` version of Weaviate to `1.25` on kubernetes, you must follow these steps:

- Delete the deployed [`StatefulSet`](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/)
- Update the helm chart to version `17.0.0` or higher
- Re-deploy Weaviate
- Wait for cluster metadata migration to complete

For more details, refer to the [upgrade instructions](https://docs.weaviate.io/deploy/migration/weaviate-1-25#upgrade-instructions) below.

To downgrade from `1.25` to a pre-`1.25` version, you must perform a `POST` request to the `v1/cluster/schema-v1` endpoint to downgrade the metadata. Then, you must similarly delete the deployed `StatefulSet` and downgrade Weaviate to the desired version.

For more details, refer to the [downgrade instructions](https://docs.weaviate.io/deploy/migration/weaviate-1-25#downgrade-instructions) below.

> [!WARNING]
>
> **Cluster downtime**
>
> This upgrade requires a cluster metadata migration. The cluster requires some downtime for the migration. The length of the downtime depends on the size of the database.
>
>
>
> We suggest performing this upgrade at a least disruptive time, or even provisioning a secondary cluster while the main cluster is being restarted.

## Upgrade instructions

> [!NOTE]
>
> **namespace**
>
> If your deployment is on another namespace, modify the instructions below accordingly, where it follows `-n`. For example, if your deployment is on `my_namespace` , the first command will become `kubectl delete sts weaviate -n my_namespace`.

### (Optional) Backup

Before proceeding with the upgrade, we recommend making a [backup](https://docs.weaviate.io/deploy/configuration/backups) of your Weaviate Database. If a backup is not possible, you can explore other options, such as manually [exporting your data](https://docs.weaviate.io/weaviate/manage-collections/migrate)

### 1. Delete StatefulSet

First, delete the existing StatefulSet. This will delete all the pods in the namespace.

```bash
kubectl delete sts weaviate -n weaviate
```

You should see an output like this:

```bash
statefulset.apps "weaviate" deleted
```

Once the StatefulSet is deleted, you should not see any pods in the namespace.

```bash
kubectl get pods -n weaviate
```

### 2. Update Helm Chart

Then, update the repository to fetch the latest changes:

```bash
helm repo update weaviate
```

Check the helm chart version as shown below. (It should be at least `17.0.0`.)

```bash
helm search repo weaviate
```

### 3. Deploy Weaviate

Then, re-deploy Weaviate as shown below. This will apply your existing configuration file `values.yaml`, and allow the Weaviate cluster to restart anew under the new consensus algorithm (Raft).

Here, the image tag is overridden to `1.25.0`. You can also modify this value directly in the `values.yaml` file.

```bash
helm upgrade weaviate weaviate/weaviate \
  --namespace weaviate \
  --values ./values.yaml \
  --set image.tag="1.25.0"
```

### 4. Verify update

The pods may take a little bit of time to get up and running again. To confirm that the cluster is up and running, you can view the `v1/cluster/statistics` endpoint.

For example, you can use `curl` (and `jq` for pretty printing) to check the status of the cluster. (Remember to replace `localhost:8080` with the correct URL & port.)

```bash
curl -s localhost:8080/v1/cluster/statistics | jq
```

If successful, you should see a response similar to this:

```json
{
  "statistics": [
    {
      // ...
      "leaderAddress": "10.244.2.3:8300",
      "leaderId": "weaviate-0",
      "name": "weaviate-0",
      "open": true,
      "raft": {},
      "ready": true,
      "status": "HEALTHY"
    },
    {
      // ...
      "leaderAddress": "10.244.1.3:8300",
      "leaderId": "weaviate-1",
      "name": "weaviate-1",
      "open": true,
      "raft": {},
      "ready": true,
      "status": "HEALTHY"
    },
    {
      // ...
      "leaderAddress": "10.244.0.4:8300",
      "leaderId": "weaviate-2",
      "name": "weaviate-2",
      "open": true,
      "raft": {},
      "ready": true,
      "status": "HEALTHY"
    }
  ],
  "synchronized": true
}
```

If the number of objects under `statistics` matches the number of replicas you have set in your `values.yaml` file, and the `synchronized` flag is `true`, then the cluster is up and running.

## Downgrade instructions

> [!WARNING]
>
> **Only for servers before `v1.35`**
>
> The `v1/cluster/schema-v1` endpoint used in step 1 was removed in `v1.35.0`. This procedure works only on a server running `v1.34.x` or earlier; on `v1.35` and later the request returns `404`, and there is no replacement endpoint. Do not delete the StatefulSet expecting the rest of the steps to work — contact support before downgrading a `v1.35` or later cluster.

If you need to downgrade from `1.25` to a pre-`1.25` version, you must perform a `POST` request to the `v1/cluster/schema-v1` (a payload is not required) to downgrade the cluster metadata.

### 1. Downgrade cluster metadata

Perform the following request to downgrade the cluster metadata. This will prepare the cluster for a downgrade to a pre-`1.25` version. (Remember to replace `localhost:8080` with the correct URL & port.)

```bash
curl -X POST -s -o /dev/null -w "%{http_code}" localhost:8080/v1/cluster/schema-v1
```

This should return a `200` status code.

### 2. Delete StatefulSet

After downgrading the cluster metadata, delete the existing StatefulSet. This will delete all the pods in the namespace.

```bash
kubectl delete sts weaviate -n weaviate
```

### 3. Downgrade Weaviate

Now, proceed with the downgrade of Weaviate. Run the following command, for example, to downgrade to version `1.24.10`.

```bash
helm upgrade weaviate weaviate/weaviate \
  --namespace weaviate \
  --values ./values.yaml \
  --set image.tag="1.24.10"
```

This should bring the cluster back to your specified pre-`1.25` version.
