Upgrading

Materialize releases new Self-Managed versions per the schedule outlined in Release schedule.

General rules for upgrading

When upgrading:

• Always check the version specific upgrade notes.

• Always upgrade the Materialize Operator before upgrading the Materialize instances.

Upgrading the Helm Chart and Materialize Operator

Update the Helm Chart repository

To update your Materialize Helm Chart repository:

helm repo update materialize

View the available chart versions:

helm search repo materialize/materialize-operator --versions

Upgrade your Materialize Operator

The Materialize Kubernetes Operator is deployed via Helm and can be updated through standard helm upgrade command:

helm upgrade -n <namespace> <release-name> materialize/materialize-operator \
  --version <new_version> \
  -f <your-custom-values.yml>

You can use helm list to find your release name. For example, if your Operator is running in the namespace materialize, run helm list:

helm list -n materialize

Retrieve the name associated with the materialize-operator CHART; for example, my-demo in the following helm list:

NAME    	  NAMESPACE  	REVISION	UPDATED                             	STATUS  	CHART                                          APP VERSION
my-demo	materialize	1      2025-12-08 11:39:50.185976 -0500 EST	deployed	materialize-operator-v26.1.0    v26.1.0

Then, to upgrade:

helm upgrade -n materialize my-demo materialize/operator \
  -f my-values.yaml \
  --version v26.1.1

Upgrading Materialize Instances

After you have upgraded your Materialize Operator, upgrade your Materialize instance(s) to the APP Version of the Operator. To find the version of your currently deployed Materialize Operator:

helm list -n materialize

You will use the returned App Version for the updated environmentdImageRef value. Specifically, for your Materialize instance(s), set environmentdImageRef value to use the new version:

spec:
  environmentdImageRef: docker.io/materialize/environmentd:<app_version>

To minimize unexpected downtime and avoid connection drops at critical periods for your application, the upgrade process involves two steps:

• First, stage the changes (update the environmentdImageRef with the new version) to the Materialize custom resource. The Operator watches for changes but does not automatically roll out the changes.

• Second, roll out the changes by specifying a new UUID for requestRollout.

Stage the Materialize instance version change

To stage the Materialize instances version upgrade, update the environmentdImageRef field in the Materialize custom resource spec to the compatible version of your currently deployed Materialize Operator.

To stage, but not rollout, the Materialize instance version upgrade, you can use the kubectl patch command; for example, if the App Version is v26.1.1:

kubectl patch materialize <instance-name> \
  -n <materialize-instance-namespace> \
  --type='merge' \
  -p "{\"spec\": {\"environmentdImageRef\": \"docker.io/materialize/environmentd:v26.1.1\"}}"

Applying the changes via requestRollout

To apply chang Materialize instance upgrade, you must update the requestRollout field in the Materialize custom resource spec to a new UUID. Be sure to consult the Rollout Configurations to ensure you’ve selected the correct rollout behavior.

# Then trigger the rollout with a new UUID
kubectl patch materialize <instance-name> \
  -n <materialize-instance-namespace> \
  --type='merge' \
  -p "{\"spec\": {\"requestRollout\": \"$(uuidgen)\"}}"

Staging and applying in a single command

Although separating the staging and rollout of the changes into two steps can minimize unexpected downtime and avoid connection drops at critical periods, you can, if preferred, combine both operations in a single command

kubectl patch materialize <instance-name> \
  -n materialize-environment \
  --type='merge' \
  -p "{\"spec\": {\"environmentdImageRef\": \"docker.io/materialize/environmentd:v26.1.1\", \"requestRollout\": \"$(uuidgen)\"}}"

Using YAML Definition

Alternatively, you can update your Materialize custom resource definition directly:

apiVersion: materialize.cloud/v1alpha1
kind: Materialize
metadata:
  name: 12345678-1234-1234-1234-123456789012
  namespace: materialize-environment
spec:
  environmentdImageRef: materialize/environmentd:v26.1.1 # Update version as needed
  requestRollout: 22222222-2222-2222-2222-222222222222    # Use a new UUID
  forceRollout: 33333333-3333-3333-3333-333333333333      # Optional: for forced rollouts
  inPlaceRollout: false                                   # In Place rollout is deprecated and ignored. Please use rolloutStrategy
  rolloutStrategy: WaitUntilReady                         # The mechanism to use when rolling out the new version. Can be WaitUntilReady or ImmediatelyPromoteCausingDowntime
  backendSecretName: materialize-backend

Apply the updated definition:

kubectl apply -f materialize.yaml

Rollout Configuration

requestRollout

Specify a new UUID value for the requestRollout to roll out the changes to the Materialize instance.

# Only rolls out if there are changes
kubectl patch materialize <instance-name> \
  -n <materialize-instance-namespace> \
  --type='merge' \
  -p "{\"spec\": {\"requestRollout\": \"$(uuidgen)\"}}"

requestRollout with forcedRollouts

Specify a new UUID value for forcedRollout to roll out even when there are no changes to the instance. Use forcedRollout with requestRollout.

kubectl patch materialize <instance-name> \
  -n materialize-environment \
  --type='merge' \
  -p "{\"spec\": {\"requestRollout\": \"$(uuidgen)\", \"forceRollout\": \"$(uuidgen)\"}}"

Rollout strategies

The behavior of the new version rollout follows your rolloutStrategy setting:

Verifying the Upgrade

After initiating the rollout, you can monitor the status field of the Materialize custom resource to check on the upgrade.

# Watch the status of your Materialize environment
kubectl get materialize -n materialize-environment -w

# Check the logs of the operator
kubectl logs -l app.kubernetes.io/name=materialize-operator -n materialize

Upgrade guides

The following upgrade guides are available:

Upgrade using Helm Commands

Upgrade using Unified Terraform Modules

Upgrade using Legacy Terraform Modules

Version Specific Upgrade Notes

Upgrading to v26.1 and later versions

• To upgrade to v26.1 or future versions, you must first upgrade to v26.0

Upgrading to v26.0

• Upgrading to v26.0.0 is a major version upgrade. To upgrade to v26.0 from v25.2.X or v25.1, you must first upgrade to v25.2.16 and then upgrade to v26.0.0.

• For upgrades, the inPlaceRollout setting has been deprecated and will be ignored. Instead, use the new setting rolloutStrategy to specify either:

  • WaitUntilReady (Default)
  • ImmediatelyPromoteCausingDowntime

  For more information, see rolloutStrategy.

• New requirements were introduced for license keys. To upgrade, you will first need to add a license key to the backendSecret used in the spec for your Materialize resource.

  See License key for details on getting your license key.

• Swap is now enabled by default. Swap reduces the memory required to operate Materialize and improves cost efficiency. Upgrading to v26.0 requires some preparation to ensure Kubernetes nodes are labeled and configured correctly. As such:

  • If you are using the Materialize-provided Terraforms, upgrade to version v0.6.1 of the Terraform.

  • If you are not using a Materialize-provided Terraform, refer to Prepare for swap and upgrade to v26.0.

Upgrading between minor versions less than v26

• Prior to v26, you must upgrade at most one minor version at a time. For example, upgrading from v25.1.5 to v25.2.16 is permitted.

See also

• Materialize Operator Configuration

• Materialize CRD Field Descriptions

• Troubleshooting