You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -44,62 +43,58 @@ helm upgrade my-materialize-operator materialize/misc/helm-charts/operator -f my
44
43
45
44
### Upgrading Materialize Instances
46
45
47
-
{{< important >}}
48
-
49
-
Always upgrade your Materialize instances after upgrading the operator to
50
-
ensure compatibility.
51
-
52
-
{{</ important >}}
53
-
54
-
To upgrade your Materialize instances, you'll need to update the Materialize custom resource and trigger a rollout.
46
+
In order to minimize unexpected downtime and avoid connection drops at critical
47
+
periods for your application, changes are not immediately and automatically
48
+
rolled out by the Operator. Instead, the upgrade process involves two steps:
49
+
- First, staging spec changes to the Materialize custom resource.
50
+
- Second, applying the changes via a `rolloutRequest`.
55
51
56
-
By default, the operator performs rolling upgrades (`inPlaceRollout: false`) which minimize downtime but require additional Kubernetes cluster resources during the transition. However, keep in mind that rolling upgrades typically take longer to complete due to the sequential rollout process. For environments where downtime is acceptable, you can opt for in-place upgrades (`inPlaceRollout: true`).
52
+
When upgrading your Materialize instances, you'll first want to update the `environmentdImageRef` field in the Materialize custom resource spec.
57
53
58
-
#### Determining the Version
59
-
60
-
The compatible version for your Materialize instances is specified in the Helm chart's `appVersion`. For the installed chart version, you can run:
54
+
#### Updating the `environmentdImageRef`
55
+
To find a compatible version with your currently deployed Materialize operator, check the `appVersion` in the Helm repository.
61
56
62
57
```shell
63
58
helm list -n materialize
64
59
```
65
60
66
-
Or check the `Chart.yaml` file in the `misc/helm-charts/operator` directory:
61
+
Using the returned version, we can construct an image ref.
62
+
We always recommend using the official Materialize image repository
63
+
`docker.io/materialize/environmentd`.
67
64
68
-
```yaml
69
-
apiVersion: v2
70
-
name: materialize-operator
71
-
# ...
72
-
version: 25.1.0-beta.1
73
-
appVersion: v0.125.2 # Use this version for your Materialize instances
To apply changes and kick off the Materialize instance upgrade, you must update the `requestRollout` field in the Materialize custom resource spec to a new UUID.
81
+
Be sure to consult the [Rollout Configurations](#rollout-configuration) to ensure you've selected the correct rollout behavior.
The behavior of a forced rollout follows your `inPlaceRollout` setting:
141
-
- With `inPlaceRollout: false` (default): Creates new instances before terminating the old ones, temporarily requiring twice the resources during the transition
142
-
- With `inPlaceRollout: true`: Directly replaces the instances, causing downtime but without requiring additional resources
138
+
#### Rollout Strategies
139
+
The behavior of the new version rollout follows your `rolloutStrategy` setting:
140
+
141
+
`WaitUntilReady` (default):
142
+
143
+
New instances are created and all dataflows are determined to be ready before cutover and terminating the old version, temporarily requiring twice the resources during the transition.
144
+
145
+
`ImmediatelyPromoteCausingDowntime`:
146
+
147
+
Tears down the prior version before creating and promoting the new version. This causes downtime equal to the duration it takes for dataflows to hydrate, but does not require additional resources.
148
+
149
+
#### In Place Rollout
150
+
151
+
`inPlaceRollout` has been deprecated and will be ignored.
152
+
143
153
144
154
### Verifying the Upgrade
145
155
146
-
After initiating the rollout, you can monitor the status:
156
+
After initiating the rollout, you can monitor the status field of the Materialize custom resource to check on the upgrade.
147
157
148
158
```shell
149
159
# Watch the status of your Materialize environment
@@ -152,15 +162,22 @@ kubectl get materialize -n materialize-environment -w
- `requestRollout`triggers a rollout only if there are actual changes to the instance (like image updates)
159
-
- `forceRollout`triggers a rollout regardless of whether there are changes, which can be useful for debugging or when you need to force a rollout for other reasons
160
-
- Both fields expect UUID values and each rollout requires a new, unique UUID value
161
-
- `inPlaceRollout`:
162
-
- When `false` (default): Performs a rolling upgrade by spawning new instances before terminating old ones. While this minimizes downtime, there may still be a brief interruption during the transition.
163
-
- When `true`: Directly replaces existing instances, which will cause downtime.
165
+
### Version Specific Upgrade Notes
166
+
167
+
#### Upgrading to `v26.0`
168
+
- This is a major version upgrade. In order to upgrade to `v26.0`, you must first upgrade to `v25.2.15`, then upgrade to `v26.0.0`.
169
+
- New requirements were introduced for license keys. In order to upgrade, you will
170
+
first need to add a license key to the `backendSecret` used in the spec for your
171
+
Materialize resource. Please refer to our [instructions on how to get and install a license keys](/installation/faq#how-do-i-get-a-license-key).
172
+
- Swap is now enabled by default. Swap reduces the memory required to
173
+
operate Materialize and improves cost efficiency. Upgrading to `v26.0`
174
+
requires some preparation to ensure kubernetes nodes are labeled
175
+
and configured correctly. Please refer to our guide on [swap node
176
+
preparation](/installation/upgrade-to-swap).
177
+
178
+
179
+
#### Upgrading between minor versions less than `v26`
180
+
- Prior to `v26`, you must upgrade at most one minor version at a time. For example, upgrading from `v25.1.5` to `v25.2.15` is permitted.
0 commit comments