Upgrade on kind

To upgrade your Materialize instances, first choose a new operator version and upgrade the Materialize operator. Then, upgrade your Materialize instances to the same version. 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.

! Important: When performing major version upgrades, you can upgrade only one major version at a time. For example, upgrades from v26.1.0 to v27.2.0 is permitted but v26.1.0 to v28.0.0 is not. Skipping major versions or downgrading is not supported. To upgrade from v25.2 to v26.0, you must upgrade first to v25.2.15+.

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.

License key

Starting in v26.0, Materialize requires a license key. If your existing deployment does not have a license key configured, contact Materialize support.

Upgrade

! Important: The following procedure performs a rolling upgrade, where both the old and new Materialize instances are running before the the old instance are removed. When performing a rolling upgrade, ensure you have enough resources to support having both the old and new Materialize instances running.

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=v26.0.0

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 sample-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 v26.0.0 \
-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:

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

As of v26.0, Self-Managed Materialize requires a license key. If your deployment has not been configured with a license key:

a. Contact Materialize support.

b. Once you have your license key, run the following command to add it to the materialize-backend secret:
```
kubectl -n materialize-environment patch secret materialize-backend -p '{"stringData":{"license_key":"<your license key goes here>"}}' --type=merge
```

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

Field	Description
`environmentdImageRef`	Update the version to the new version. This should be the same as the operator version: `v26.0.0`.
`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:v26.0.0 # 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.

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:
```
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.
Open the Materialize Console. The Console should display the new version.