Home  /  Installation  /  Install locally on kind

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 Release date Notes
v25.1.10 v0.142.1 v0.130.11 2025-04-24
v25.1.9 v0.141.0 v0.130.10 2025-04-24
v25.1.8 v0.138.0 v0.130.9 2025-04-24
v25.1.7 v0.138.0 v0.130.8 2025-04-08
v25.1.6 v0.130.8 v0.130.8 2025-03-26 This release uses an incorrect version of orchestratord as its default (v0.130.8 instead of v0.138.0). This has been fixed in v25.1.7.
v25.1.5 v0.138.0 v0.130.7 2025-03-25
v25.1.4 v0.138.0 v0.130.7 2025-03-25
v25.1.2 v0.130.4 v0.130.4 2025-03-11

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

! Important:

The following procedure performs an in-place upgrade, which incurs downtime.

To perform a rolling upgrade(where both the old and new Materialize instances are running before the the old instances are removed), you can specify inPlaceRollout to false. When performing a rolling upgrade, ensure you have enough resources to support having both the old and new Materialize instances running.

  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=v0.153.0

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.1.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:

    MZ_OPERATOR=$(kubectl -n materialize get pods --no-headers | grep operator  | awk '{print $1}')
kubectl -n materialize describe pod/$MZ_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 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.14 # 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

  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:

    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.

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

See also

Back to top ↑