Upgrade on kind

To upgrade your Materialize instances, upgrade the Materialize operator first and then the Materialize instances. The following tutorial upgrades your Materialize deployment running locally on a kind cluster.

The tutorial assumes you have installed Materialize on kind using the instructions on Install locally on kind.

Version compatibility

When updating, you need to specify the Materialize Operator version, orchestratord version, and the environmentd versions. The following table presents the versions compatibility for the operator and the applications:

Materialize Operator	orchestratord version	environmentd version
v25.1.2	v0.130.4	v0.130.4

Prerequisites

Helm 3.2.0+

If you don’t have Helm version 3.2.0+ installed, install. For details, see the Helm documentation.

`kubectl`

This tutorial uses kubectl. To install, refer to the kubectl documentationq.

For help with kubectl commands, see kubectl Quick reference.

Upgrade

Open a Terminal window.
Go to your Materialize working directory.
```
cd my-local-mz
```
Upgrade the Materialize Helm chart.
```
helm repo update materialize
```
Get the sample configuration files for the new version.
```
mz_version=v0.130.4

curl -o upgrade-values.yaml https://raw.githubusercontent.com/MaterializeInc/materialize/refs/tags/$mz_version/misc/helm-charts/operator/values.yaml
```
If you have previously modified the values.yaml file for your deployment, include the changes into the upgrade-values.yaml file.

Upgrade the Materialize Operator, specifying the new version and the updated configuration file. Include any additional configurations that you specify for your deployment.

helm upgrade my-materialize-operator materialize/materialize-operator \
--namespace=materialize \
--version v25.1.2 \
-f upgrade-values.yaml \
--set observability.podMetrics.enabled=true

Verify that the operator is running:

kubectl -n materialize get all

Verify the operator upgrade by checking its events:

MZ_OPERATOR=$(kubectl -n materialize get pods --no-headers | grep operator  | awk '{print $1}')
kubectl -n materialize describe pod/$MZ_OPERATOR

Create a new upgrade-materialize.yaml file with the following content:

Field	Description
`environmentdImageRef`	Update the version to the new version.
`requestRollout` or `forceRollout`	Enter a new UUID. Can be generated with `uuidgen`. `requestRollout` triggers a rollout only if changes exist. `forceRollout` triggers a rollout even if no changes exist.
`inPlaceRollout`	Set to `true` to perform an in-place upgrade. Set to `false` to perform a rolling upgrade. For rolling upgrades, ensure you have enough resources to support having both the old and new Materialize instances running during the upgrade.

apiVersion: materialize.cloud/v1alpha1
kind: Materialize
metadata:
  name: 12345678-1234-1234-1234-123456789012
  namespace: materialize-environment
spec:
  environmentdImageRef: materialize/environmentd:v0.130.4 # Update version
  requestRollout: 22222222-2222-2222-2222-222222222222    # Enter a new UUID
  # forceRollout: 33333333-3333-3333-3333-333333333333    # For forced rollouts
  inPlaceRollout: true                                    # When false,  performs a rolling upgrade rather than in-place
  backendSecretName: materialize-backend

Apply the upgrade-materialize.yaml file to your Materialize instance:
```
kubectl apply -f upgrade-materialize.yaml
```

Verify that the components are running after the upgrade:

kubectl -n materialize-environment get all

Verify upgrade by checking the balancerd events:

MZ_BALANCERD=$(kubectl -n materialize-environment get pods --no-headers | grep balancerd  | awk '{print $1}')
kubectl -n materialize-environment describe pod/$MZ_BALANCERD

The Events section should list that the new version of the balancerd have been pulled.

Verify the upgrade by checking the environmentd events:

MZ_ENVIRONMENTD=$(kubectl -n materialize-environment get pods --no-headers | grep environmentd  | awk '{print $1}')
kubectl -n materialize-environment describe pod/$MZ_ENVIRONMENTD

The Events section should list that the new version of the environmentd have been pulled.

Open the Materialize Console. The Console should display the new version.