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:

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

1. Open a Terminal window.

2. Go to your Materialize working directory.

   cd my-local-mz
   

3. Upgrade the Materialize Helm chart.

   helm repo update materialize
   

4. Get the sample configuration files for the new version.

   mz_operator_version=self-managed-v25.2.13
   
   curl -o upgrade-values.yaml https://raw.githubusercontent.com/MaterializeInc/materialize/refs/tags/$mz_operator_version/misc/helm-charts/operator/values.yaml
   

   If you have previously modified the sample-values.yaml file for your deployment, include the changes into the upgrade-values.yaml file.

5. 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.2.13 \
   -f upgrade-values.yaml \
   --set observability.podMetrics.enabled=true
   

6. Verify that the operator is running:

   kubectl -n materialize get all
   

   Verify the operator upgrade by checking its events:

   kubectl -n materialize describe pod -l app.kubernetes.io/name=materialize-operator
   

7. 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 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.147.18 # Update version
     requestRollout: 22222222-2222-2222-2222-222222222222    # Enter a new UUID
     # forceRollout: 33333333-3333-3333-3333-333333333333    # For forced rollouts
     inPlaceRollout: false                                   # When false, performs a rolling upgrade rather than in-place
     backendSecretName: materialize-backend
   

   WARNING! Please consult the Materialize team before setting inPlaceRollout to true and performing an in-place rollout. In almost all cases a rolling upgrade is preferred.

8. Apply the upgrade-materialize.yaml file to your Materialize instance:

   kubectl apply -f upgrade-materialize.yaml
   

9. Verify that the components are running after the upgrade:

   kubectl -n materialize-environment get all
   

   Verify upgrade by checking the balancerd events:

   kubectl -n materialize-environment describe pod -l app=balancerd
   

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

   Verify the upgrade by checking the environmentd events:

   kubectl -n materialize-environment describe pod -l app=environmentd
   

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

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

See also

• Materialize Operator Configuration
• Troubleshooting
• Installation