Upgrade on kind

View as Markdown

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.16+.

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 documentation.

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 old instances 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.31.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.
Check the CRD version (v1alpha1 or, available starting in Materialize v26.30, v1) being used for your Materialize instance.
To determine which CRD version is in use, run the following command, replacing with your instance name. For the sample-materialize.yaml used in this example, the instance name is 12345678-1234-1234-1234-123456789012:
```
kubectl get materialize <instance-name> -n materialize-environment \
     -o jsonpath='{.metadata.annotations.kubectl\.kubernetes\.io/last-applied-configuration}' \
   | python3 -c 'import sys,json; print(json.load(sys.stdin)["apiVersion"])'
   
```
Upgrade the Materialize Operator, specifying the new version and the updated configuration file. Include any additional configurations that you specify for your deployment.

Select the tab for your Materialize CRD API version (v1alpha1 or, available starting in Materialize v26.30, v1) your deployment currently uses. This step does not cover migrating from v1alpha1 to v1 (including setting up prerequisites).
If currently using v1 (available starting in Materialize v26.30):
helm upgrade my-materialize-operator materialize/materialize-operator \ --namespace=materialize \ --version v26.31.0 \ -f upgrade-values.yaml \ --set observability.podMetrics.enabled=true \ --set operator.args.installV1CRD=true
If currently using v1alpha1 (default):
helm upgrade my-materialize-operator materialize/materialize-operator \ --namespace=materialize \ --version v26.31.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, updating the following fields:

Select the tab for the CRD API version your deployment currently uses. This step does not cover migrating from v1alpha1 to v1. (The v1 CRD API version is available starting in Materialize v26.30.)

If using v1, update the following fields:

Field	Description
`environmentdImageRef`	Update the version to the new version. This should be the same as the operator version: `v26.31.0`. Updating this field automatically triggers a rollout.
`forceRollout`	Optional. Set to a new UUID (can be generated with `uuidgen`) only to force a rollout when no other changes exist.

apiVersion: materialize.cloud/v1
kind: Materialize
metadata:
  name: 12345678-1234-1234-1234-123456789012
  namespace: materialize-environment
spec:
  environmentdImageRef: materialize/environmentd:v26.31.0 # Update version
  # forceRollout: 33333333-3333-3333-3333-333333333333    # For forced rollouts
  rolloutStrategy: WaitUntilReady                         # The mechanism to use when rolling out the new version.
  backendSecretName: materialize-backend

v1alpha1 is the default CRD version for a Materialize instance. With v1alpha1, instance rollouts require manually rotating a UUID.

If using v1alpha1, update the following fields:

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

apiVersion: materialize.cloud/v1alpha1
kind: Materialize
metadata:
  name: 12345678-1234-1234-1234-123456789012
  namespace: materialize-environment
spec:
  environmentdImageRef: materialize/environmentd:v26.31.0 # Update version
  requestRollout: 22222222-2222-2222-2222-222222222222    # Enter a new UUID
# forceRollout: 33333333-3333-3333-3333-333333333333    # For forced rollouts
  rolloutStrategy: WaitUntilReady                         # The mechanism to use when rolling out the new version.
  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:
```
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.