update upgrade docs for v26

Author: jubrad

doc/user/content/installation/upgrading.md

@@ -22,6 +22,9 @@ When upgrading:
 - Always upgrade your Materialize instances after upgrading the operator to
   ensure compatibility.
 
+- Always check the [version specific upgrade notes](#version-specific-upgrade-notes).
+
+
 ### Upgrading the Helm Chart
 
 {{< important >}}
@@ -53,8 +56,6 @@ ensure compatibility.
 
 To upgrade your Materialize instances, you'll need to update the Materialize custom resource and trigger a rollout.
 
-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`).
-
 #### Determining the Version
 
 The compatible version for your Materialize instances is specified in the Helm chart's `appVersion`. For the installed chart version, you can run:
@@ -69,11 +70,11 @@ Or check the `Chart.yaml` file in the `misc/helm-charts/operator` directory:
 apiVersion: v2
 name: materialize-operator
 # ...
-version: 25.1.0-beta.1
-appVersion: v0.125.2  # Use this version for your Materialize instances
+version: 26.0.0
+appVersion: v26.0.0  # Use this version for your Materialize instances
 ```
 
-Use the `appVersion` (`v0.125.2` in this case) when updating your Materialize instances to ensure compatibility.
+Use the `appVersion` (`v26.0.0` in this case) when updating your Materialize instances to ensure compatibility.
 
 #### Using `kubectl` patch
 
@@ -84,7 +85,7 @@ For standard upgrades such as image updates:
 kubectl patch materialize <instance-name> \
   -n <materialize-instance-namespace> \
   --type='merge' \
-  -p "{\"spec\": {\"environmentdImageRef\": \"materialize/environmentd:v0.125.2\"}}"
+  -p "{\"spec\": {\"environmentdImageRef\": \"materialize/environmentd:v26.0.0\"}}"
 
 # Then trigger the rollout with a new UUID
 kubectl patch materialize <instance-name> \
@@ -99,7 +100,7 @@ You can combine both operations in a single command if preferred:
 kubectl patch materialize 12345678-1234-1234-1234-123456789012 \
   -n materialize-environment \
   --type='merge' \
-  -p "{\"spec\": {\"environmentdImageRef\": \"materialize/environmentd:v0.125.2\", \"requestRollout\": \"$(uuidgen)\"}}"
+  -p "{\"spec\": {\"environmentdImageRef\": \"materialize/environmentd:v26.0.0\", \"requestRollout\": \"$(uuidgen)\"}}"
 ```
 
 #### Using YAML Definition
@@ -113,10 +114,11 @@ metadata:
   name: 12345678-1234-1234-1234-123456789012
   namespace: materialize-environment
 spec:
-  environmentdImageRef: materialize/environmentd:v0.125.2 # Update version as needed
+  environmentdImageRef: materialize/environmentd:v26.0.0 # Update version as needed
   requestRollout: 22222222-2222-2222-2222-222222222222    # Generate new UUID
   forceRollout: 33333333-3333-3333-3333-333333333333      # Optional: for forced rollouts
-  inPlaceRollout: false                                   # When false, performs a rolling upgrade rather than in-place
+  inPlaceRollout: false                                   # In Place rollout is depecrated 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
 ```
 
@@ -137,9 +139,9 @@ kubectl patch materialize <instance-name> \
   -p "{\"spec\": {\"requestRollout\": \"$(uuidgen)\", \"forceRollout\": \"$(uuidgen)\"}}"
 ```
 
-The behavior of a forced rollout follows your `inPlaceRollout` setting:
-- With `inPlaceRollout: false` (default): Creates new instances before terminating the old ones, temporarily requiring twice the resources during the transition
-- With `inPlaceRollout: true`: Directly replaces the instances, causing downtime but without requiring additional resources
+The behavior of a the new version rollout follows your `rolloutStrategy` setting:
+- With `WaitUntilReady` (default): New instances are created and all dataflows are determined to be ready before cuto over and termination the old version, temporarily requiring twice the resources during the transition
+- With `ImmediatelyPromoteCausingDowntime`: Tears down the prior version before creating and promoting the new version. This causes downtime equal to the duration it takes for datalfows to hydrate, but does not require additional resources
 
 ### Verifying the Upgrade
 
@@ -155,12 +157,23 @@ kubectl logs -l app.kubernetes.io/name=materialize-operator -n materialize
 
 ### Notes on Rollouts
 
-- `requestRollout` triggers a rollout only if there are actual changes to the instance (like image updates)
-- `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
-- Both fields expect UUID values and each rollout requires a new, unique UUID value
-- `inPlaceRollout`:
-  - 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.
-  - When `true`: Directly replaces existing instances, which will cause downtime.
+- `requestRollout` triggers a rollout only if there are actual changes to the instance (like image updates) - requires a new UUID each rollout.
+- `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 - requires a new UUID each rollout
+- `rolloutStrategy`:
+    - `WaitUntilReady` (default): New instances are created and all dataflows are determined to be ready before cuto over and termination the old version, temporarily requiring twice the resources during the transition
+    - `ImmediatelyPromoteCausingDowntime`: Tears down the prior version before creating and promoting the new version. This causes downtime equal to the duration it takes for datalfows to hydrate, but does not require additional resources
+- `inPlaceRollout`: Deprecated and ignored. Please use `rolloutStrategy`.
+
+### Version Specific Upgrade Notes
+
+#### Upgrading to `v26`
+- `v26` is a major version upgrade. In order to upgrade to `v26` you must first upgrade to `v25.2.15`, then upgrade to `v26.0.0`.
+- `v26` introduced a new requirement for license keys. In order to upgrade you will first need to add a license key to the `backendSecret` used in the spec for your Materialize resource.
+# TODO link to licence key doc / community license key marketing page
+
+
+#### Upgrading between minor versions less than `v26`
+ - Prior to `v26` it is always required to upgrade at most one minor version at a time. For example upgrading from `v25.1.5` to `v25.2.15` is permitted.
 
 ## See also