Review the notes for your target version before upgrading. For the general upgrade procedure, see the upgrade guides.

Upgrading to v26.30 and later versions

v26.30.0 introduces support for a new version of the Materialize CRD, v1, which provides simplified rollouts. Previously, Materialize only supported v1alpha1; v1alpha1 remains the default.

Upgrading to v26.30+ does not require adopting the v1 CRD; adopting v1 is opt-in. You can upgrade as usual while continuing to use v1alpha1; your existing instances will behave exactly as before. However, once you are on v26.30+, we do recommend you schedule adoption of v1 before the next major release.

If using Materialize-provided TF modules, v3.1.1+ automatically handles the prerequisites for adopting v1. It does not switch your instances to v1. To switch to v1, see Switch to v1 CRD.

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.