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 for your target version:

  • Upgrading to v26.30 and later versions
  • Upgrading to v26.1 and later versions
  • Upgrading to v26.0
  • Upgrading between minor versions less than v26
• Always upgrade the Materialize Operator before upgrading the Materialize instances.

Upgrade guides

The following upgrade guides are available as examples:

Upgrade using Helm Commands

Upgrade using the new Terraform Modules

Upgrade using Legacy Terraform Modules

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

Upgrading Materialize Instances

After upgrading the operator, upgrade each Materialize instance to the operator’s App Version by updating its environmentdImageRef. For step-by-step instructions, use the upgrade guide for your environment (Kind, AWS, Azure, or GCP). This section explains how instance rollouts work.

Rollout configuration

Materialize supports two CRD API versions: v1alpha1 (default) and v1 (available starting in v26.30).

How you trigger a rollout depends on the CRD API version of your instances.

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

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

Rollout strategies

Rollout strategies control how Materialize transitions from the current generation to a new generation during an upgrade. The behavior follows your rolloutStrategy setting.

WaitUntilReady — Default

WaitUntilReady creates a new generation of pods and automatically promotes them as soon as they catch up to the old generation and become ReadyToPromote. Because both generations run simultaneously until the promotion, this strategy temporarily doubles the required resources to run Materialize.

ImmediatelyPromoteCausingDowntime

ImmediatelyPromoteCausingDowntime tears down the prior generation and immediately promotes the new generation without waiting for it to hydrate. This causes downtime until the new generation has hydrated. However, it does not require additional resources.

ManuallyPromote

ManuallyPromote allows you to choose when to promote the new generation. This means you can time the promotion for periods when load is low, minimizing the impact of potential downtime for any clients connected to Materialize. This strategy temporarily doubles the required resources to run Materialize.

To minimize downtime, wait until the new generation has fully hydrated and caught up to the prior generation before promoting. To check hydration status, inspect the UpToDate condition in the Materialize resource status. When hydration completes, the condition will be ReadyToPromote.

To promote, update the forcePromote field to match the current rollout identifier (in v1, the status.requestedRolloutHash; in v1alpha1, the requestRollout UUID in the spec). If you need to promote before hydration completes, you can set forcePromote immediately, but clients may experience downtime.

Do not leave new generations unpromoted indefinitely. They should either be promoted or canceled. New generations open a read hold on the metadata database that prevents compaction. This hold is only released when the generation is promoted or canceled. If left open too long, promoting or canceling can trigger a spike in deletion load on the metadata database, potentially causing downtime. It is not recommended to leave generations unpromoted for over 6 hours.

inPlaceRollout — Deprecated (v1alpha1 only)

The setting is ignored.

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

Cancelling the upgrade

You may want to cancel an in-progress rollout if the upgrade has failed (for example, new pods are not healthy). Before cancelling, verify that the upgrade has not already completed by checking that the deploy generation (found via status.activeGeneration) is still the one from before the upgrade. Once an upgrade has already happened, you cannot revert using this method.

kubectl get materialize <instance-name> -n materialize-environment \
  -o jsonpath='{.status.lastCompletedRolloutRequest} {.status.lastCompletedRolloutEnvironmentdImageRef}'

kubectl patch materialize <instance-name> \
  -n materialize-environment \
  --type='merge' \
  -p "{\"spec\": {\"requestRollout\": \"<lastCompletedRolloutRequest-value>\", \"environmentdImageRef\": \"<lastCompletedRolloutEnvironmentdImageRef-value>\"}}"

kubectl apply -f previous_materialize_configuration.yaml

See also

• Version-specific upgrade notes

• Adopting the v1 CRD

• Materialize Operator Configuration

• Materialize CRD Field Descriptions

• Troubleshooting