docs: rename v1alpha2 to v1 and document installV1CRD opt-in

alex-hunt-materialize · claude · alex-hunt-materialize · commit ef7d33946945 · 2026-06-11T14:07:59.000+01:00
The new CRD version is now called v1 instead of v1alpha2, and the operator
only installs the v1 CRD and its conversion webhook when the
operator.args.installV1CRD helm value is set. Update the version docs to
v26.29, regenerate the CRD field descriptions from the v1 schema, and pick
up the newer rollout-cancellation instructions on the v1alpha1 page.

Co-Authored-By: Claude Fable 5 &lt;noreply@anthropic.com&gt;
diff --git a/bin/bump-version b/bin/bump-version
@@ -70,7 +70,7 @@ rm -f src/{clusterd,environmentd,materialized,persist-client,testdrive,catalog-d
 
 cargo update --workspace
 
-for crd_version in v1alpha1 v1alpha2; do
+for crd_version in v1alpha1 v1; do
     crd_descriptions_json="doc/user/data/self_managed/materialize_crd_descriptions_${crd_version}.json"
     cargo run -p mz-cloud-resources --bin crd-writer -- "${crd_version}" > "${crd_descriptions_json}"
     git add "${crd_descriptions_json}"
diff --git a/doc/user/content/releases/_index.md b/doc/user/content/releases/_index.md
@@ -1042,7 +1042,7 @@ v26.4.0 introduces several performance improvements and bugfixes.
 - **Up to 3x faster hydration times for large PostgreSQL tables**: We've reduced the overhead incurred by communication between multiple *workers* on a large cluster. We've observed up to 3x throughput improvement when ingesting 1 TB PostgreSQL tables on large clusters.
 - **More efficient source ingestion batching**: Sources now batch writes more effectively. This can result in improved freshness and lower resource utilization, especially when a source is doing a large number of writes.
 - **CloudSQL HA failover support** (<red>*Materialize Self-Managed only*</red>): Materialize Self-Managed now offers better support for handling failovers in CloudSQL HA sources, without downtime. [Contact our support team](/support/) to enable this in your environment.
-- **Manual Promotion** (<red>*Materialize Self-Managed only*</red>): [Rollout strategies](/self-managed-deployments/upgrading/materialize-instances/v1alpha2/#rollout-strategies) allow you control how Materialize transitions from the current generation to a new generation during an upgrade. We've added a new rollout strategy called `ManuallyPromote` which allows you to choose when to promote the new generation. This means that you can minimize the impact of potential downtime.
+- **Manual Promotion** (<red>*Materialize Self-Managed only*</red>): [Rollout strategies](/self-managed-deployments/upgrading/materialize-instances/v1/#rollout-strategies) allow you control how Materialize transitions from the current generation to a new generation during an upgrade. We've added a new rollout strategy called `ManuallyPromote` which allows you to choose when to promote the new generation. This means that you can minimize the impact of potential downtime.
 
 ### Bug Fixes {#v26.4-bug-fixes}
 - Fixed timestamp determination logic to handle empty read holds correctly.
@@ -1211,7 +1211,7 @@ use the new setting `rolloutStrategy` to specify either:
 - `WaitUntilReady` (*Default*)
 - `ImmediatelyPromoteCausingDowntime`
 
-For more information, see [`rolloutStrategy`](/self-managed-deployments/upgrading/materialize-instances/v1alpha2/#rollout-strategies).
+For more information, see [`rolloutStrategy`](/self-managed-deployments/upgrading/materialize-instances/v1/#rollout-strategies).
 
 ### Terraform helpers
 
diff --git a/doc/user/content/security/self-managed/authentication.md b/doc/user/content/security/self-managed/authentication.md
@@ -51,7 +51,7 @@ The following example Kubernetes manifest includes configuration for
 SASL/SCRAM-SHA-256 authentication:
 
 {{< tabs >}}
-{{< tab "v1alpha2 (v26.18+)" >}}
+{{< tab "v1 (v26.29+)" >}}
 
 ```hc {hl_lines="15 25"}
 apiVersion: v1
@@ -70,7 +70,7 @@ stringData:
   license_key: "..."
   external_login_password_mz_system: "enter_mz_system_password"
 ---
-apiVersion: materialize.cloud/v1alpha2
+apiVersion: materialize.cloud/v1
 kind: Materialize
 metadata:
   name: 12345678-1234-1234-1234-123456789012
@@ -82,7 +82,7 @@ spec:
 ```
 
 {{< /tab >}}
-{{< tab "v1alpha1 (before v26.18)" >}}
+{{< tab "v1alpha1 (before v26.29)" >}}
 
 ```hc {hl_lines="15 25"}
 apiVersion: v1
@@ -135,7 +135,7 @@ The following example Kubernetes manifest includes configuration for password
 authentication:
 
 {{< tabs >}}
-{{< tab "v1alpha2 (v26.18+)" >}}
+{{< tab "v1 (v26.29+)" >}}
 
 ```hc {hl_lines="15 25"}
 apiVersion: v1
@@ -154,7 +154,7 @@ stringData:
   license_key: "..."
   external_login_password_mz_system: "enter_mz_system_password"
 ---
-apiVersion: materialize.cloud/v1alpha2
+apiVersion: materialize.cloud/v1
 kind: Materialize
 metadata:
   name: 12345678-1234-1234-1234-123456789012
@@ -166,7 +166,7 @@ spec:
 ```
 
 {{< /tab >}}
-{{< tab "v1alpha1 (before v26.18)" >}}
+{{< tab "v1alpha1 (before v26.29)" >}}
 
 ```hc {hl_lines="15 25"}
 apiVersion: v1
diff --git a/doc/user/content/self-managed-deployments/_index.md b/doc/user/content/self-managed-deployments/_index.md
@@ -158,10 +158,10 @@ Materialize CR, see [Materialize CRD Field
 Descriptions](/self-managed-deployments/materialize-crd-field-descriptions/).
 
 {{< tabs >}}
-{{< tab "v1alpha2 (v26.18+)" >}}
+{{< tab "v1 (v26.29+)" >}}
 
 ```yaml
-apiVersion: materialize.cloud/v1alpha2
+apiVersion: materialize.cloud/v1
 kind: Materialize
 metadata:
   name: 12345678-1234-1234-1234-123456789012
@@ -172,7 +172,7 @@ spec:
 ```
 
 {{< /tab >}}
-{{< tab "v1alpha1 (before v26.18)" >}}
+{{< tab "v1alpha1 (before v26.29)" >}}
 
 ```yaml
 apiVersion: materialize.cloud/v1alpha1
@@ -194,13 +194,13 @@ creates all required Kubernetes resources.
 #### Modifying the custom resource
 
 {{< tabs >}}
-{{< tab "v1alpha2 (v26.18+)" >}}
+{{< tab "v1 (v26.29+)" >}}
 
 To modify a custom resource, update the CRD with your changes.
 When you apply the CRD, the operator will roll out the changes.
 
 {{< /tab >}}
-{{< tab "v1alpha1 (before v26.18)" >}}
+{{< tab "v1alpha1 (before v26.29)" >}}
 
 To modify a custom resource, update the CRD with your changes, including the
 `requestRollout` field with a new UUID value. When you apply the CRD, the
diff --git a/doc/user/content/self-managed-deployments/configuration-system-parameters.md b/doc/user/content/self-managed-deployments/configuration-system-parameters.md
@@ -68,10 +68,10 @@ Reference the ConfigMap in your Materialize custom resource by setting the
 `systemParameterConfigmapName` field to the name of your ConfigMap:
 
 {{< tabs >}}
-{{< tab "v1alpha2 (v26.18+)" >}}
+{{< tab "v1 (v26.29+)" >}}
 
 ```yaml {hl_lines="9"}
-apiVersion: materialize.cloud/v1alpha2
+apiVersion: materialize.cloud/v1
 kind: Materialize
 metadata:
   name: 12345678-1234-1234-1234-123456789012
@@ -83,7 +83,7 @@ spec:
 ```
 
 {{< /tab >}}
-{{< tab "v1alpha1 (before v26.18)" >}}
+{{< tab "v1alpha1 (before v26.29)" >}}
 
 ```yaml {hl_lines="9-10"}
 apiVersion: materialize.cloud/v1alpha1
@@ -151,10 +151,10 @@ Materialize custom resource YAML and update it whenever you need to force a
 ConfigMap reload:
 
 {{< tabs >}}
-{{< tab "v1alpha2 (v26.18+)" >}}
+{{< tab "v1 (v26.29+)" >}}
 
 ```yaml
-apiVersion: materialize.cloud/v1alpha2
+apiVersion: materialize.cloud/v1
 kind: Materialize
 metadata:
   name: 12345678-1234-1234-1234-123456789012
@@ -166,7 +166,7 @@ spec:
 ```
 
 {{< /tab >}}
-{{< tab "v1alpha1 (before v26.18)" >}}
+{{< tab "v1alpha1 (before v26.29)" >}}
 
 ```yaml
 apiVersion: materialize.cloud/v1alpha1
diff --git a/doc/user/content/self-managed-deployments/materialize-crd-field-descriptions/_index.md b/doc/user/content/self-managed-deployments/materialize-crd-field-descriptions/_index.md
@@ -13,5 +13,5 @@ aliases:
 
 Select the CRD API version for your Materialize deployment:
 
-- [v1alpha2 (v26.18+)](/self-managed-deployments/materialize-crd-field-descriptions/v1alpha2/)
-- [v1alpha1 (before v26.18)](/self-managed-deployments/materialize-crd-field-descriptions/v1alpha1/)
+- [v1 (v26.29+)](/self-managed-deployments/materialize-crd-field-descriptions/v1/)
+- [v1alpha1 (before v26.29)](/self-managed-deployments/materialize-crd-field-descriptions/v1alpha1/)
diff --git a/doc/user/content/self-managed-deployments/materialize-crd-field-descriptions/v1.md b/doc/user/content/self-managed-deployments/materialize-crd-field-descriptions/v1.md
@@ -1,10 +1,10 @@
 ---
-title: "v1alpha2"
-description: "Reference page on Materialize CRD Fields for the v1alpha2 API (v26.18+)"
+title: "v1"
+description: "Reference page on Materialize CRD Fields for the v1 API (v26.29+)"
 menu:
   main:
     parent: "materialize-crd-field-descriptions"
     weight: 10
 ---
 
-{{% self-managed/materialize-crd-descriptions-v1alpha2 %}}
+{{% self-managed/materialize-crd-descriptions-v1 %}}
diff --git a/doc/user/content/self-managed-deployments/materialize-crd-field-descriptions/v1alpha1.md b/doc/user/content/self-managed-deployments/materialize-crd-field-descriptions/v1alpha1.md
@@ -1,6 +1,6 @@
 ---
 title: "v1alpha1"
-description: "Reference page on Materialize CRD Fields for the v1alpha1 API (before v26.18)"
+description: "Reference page on Materialize CRD Fields for the v1alpha1 API (before v26.29)"
 menu:
   main:
     parent: "materialize-crd-field-descriptions"
diff --git a/doc/user/content/self-managed-deployments/upgrading/_index.md b/doc/user/content/self-managed-deployments/upgrading/_index.md
@@ -95,14 +95,14 @@ helm upgrade -n materialize my-demo materialize/operator \
 
 Select the instructions for your CRD API version:
 
-- [v1alpha2 (v26.18+)](/self-managed-deployments/upgrading/materialize-instances/v1alpha2/)
-- [v1alpha1 (before v26.18)](/self-managed-deployments/upgrading/materialize-instances/v1alpha1/)
+- [v1 (v26.29+)](/self-managed-deployments/upgrading/materialize-instances/v1/)
+- [v1alpha1 (before v26.29)](/self-managed-deployments/upgrading/materialize-instances/v1alpha1/)
 
 ## Version Specific Upgrade Notes
 
-### Upgrading to `v26.19` and later versions
+### Upgrading to `v26.29` and later versions
 
-{{< include-md file="shared-content/self-managed/upgrade-notes/v26.19.md" >}}
+{{< include-md file="shared-content/self-managed/upgrade-notes/v26.29.md" >}}
 
 ### Upgrading to `v26.1` and later versions
 
diff --git a/doc/user/content/self-managed-deployments/upgrading/materialize-instances/_index.md b/doc/user/content/self-managed-deployments/upgrading/materialize-instances/_index.md
@@ -18,40 +18,40 @@ Operator first. See [Upgrading the Helm Chart and Materialize Operator](/self-ma
 
 ## CRD API Versions
 
-Starting in v26.19, the Materialize Operator supports two CRD API versions:
+Starting in v26.29, the Materialize Operator supports two CRD API versions:
 
-- **v1alpha2** simplifies the upgrade process. Rollouts trigger automatically when spec fields change, removing the need to manually set a `requestRollout` UUID.
+- **v1** simplifies the upgrade process. Rollouts trigger automatically when spec fields change, removing the need to manually set a `requestRollout` UUID.
 - **v1alpha1** uses the original two-step upgrade process: first stage changes, then trigger a rollout with a new `requestRollout` UUID.
 
-Switching to v1alpha2 is **opt-in**. Upgrading the operator to v26.19+ does not change your existing v1alpha1 CRs or their behavior. You can continue using v1alpha1 indefinitely. When you are ready, you can switch individual instances to v1alpha2 at your own pace.
+Switching to v1 is **opt-in**. Upgrading the operator to v26.29+ does not change your existing v1alpha1 CRs or their behavior. You can continue using v1alpha1 indefinitely. When you are ready, you can switch individual instances to v1 at your own pace.
 
 {{< note >}}
-We recommend opting in to v1alpha2 at your convenience, as v1alpha2 behavior will become the default in the next major release.
+We recommend opting in to v1 at your convenience, as v1 behavior will become the default in the next major release.
 {{</ note >}}
 
 Select the instructions for your CRD API version:
 
-- [v1alpha2 (v26.19+)](/self-managed-deployments/upgrading/materialize-instances/v1alpha2/)
-- [v1alpha1 (before v26.19)](/self-managed-deployments/upgrading/materialize-instances/v1alpha1/)
+- [v1 (v26.29+)](/self-managed-deployments/upgrading/materialize-instances/v1/)
+- [v1alpha1 (before v26.29)](/self-managed-deployments/upgrading/materialize-instances/v1alpha1/)
 
-## Switching from v1alpha1 to v1alpha2
+## Switching from v1alpha1 to v1
 
-Switching to v1alpha2 is opt-in and does not trigger a rollout on its own. Before switching, ensure you have completed the prerequisites in the [v26.19 upgrade notes](/self-managed-deployments/upgrading/#upgrading-to-v2619-and-later-versions) (cert-manager, network/firewall changes).
+Switching to v1 is opt-in and does not trigger a rollout on its own. Before switching, ensure you have completed the prerequisites in the [v26.29 upgrade notes](/self-managed-deployments/upgrading/#upgrading-to-v2629-and-later-versions) (cert-manager, network/firewall changes), and have enabled the v1 CRD by setting the Helm value `operator.args.installV1CRD=true` on the operator. Without this value, the operator only installs the v1alpha1 CRD version, and the Kubernetes API server rejects v1 CRs.
 
 ### How it works
 
-The v1alpha1 CRD remains the storage version. When you submit a v1alpha2 CR, the operator's conversion webhook automatically converts it to v1alpha1 for storage. During conversion, the webhook computes a SHA256 hash of the spec and derives a deterministic `requestRollout` UUID from it. This means:
+The v1alpha1 CRD remains the storage version. When you submit a v1 CR, the operator's conversion webhook automatically converts it to v1alpha1 for storage. During conversion, the webhook computes a SHA256 hash of the spec and derives a deterministic `requestRollout` UUID from it. This means:
 
 - If the spec hasn't changed, the same UUID is generated, so **no unintended rollout is triggered** by switching API versions alone.
 - If the spec has changed, a different UUID is produced, automatically triggering a rollout.
 
 ### Using kubectl
 
-To switch an existing instance to v1alpha2, apply your CR with the updated `apiVersion` and remove the `requestRollout` field:
+To switch an existing instance to v1, apply your CR with the updated `apiVersion` and remove the `requestRollout` field:
 
 ```shell
 kubectl apply -f - <<EOF
-apiVersion: materialize.cloud/v1alpha2
+apiVersion: materialize.cloud/v1
 kind: Materialize
 metadata:
   name: <instance-name>
@@ -69,15 +69,15 @@ Or patch the API version on an existing CR:
 kubectl patch materialize <instance-name> \
   -n <materialize-instance-namespace> \
   --type='merge' \
-  -p '{"apiVersion":"materialize.cloud/v1alpha2"}'
+  -p '{"apiVersion":"materialize.cloud/v1"}'
 ```
 
 ### Using Terraform
 
 If you are managing your Materialize instance with the [Materialize Terraform modules](https://github.com/MaterializeInc/materialize-terraform-self-managed), set:
 
 ```hcl
-crd_version     = "v1alpha2"
+crd_version     = "v1"
 request_rollout = null
 ```
 
diff --git a/doc/user/content/self-managed-deployments/upgrading/materialize-instances/v1.md b/doc/user/content/self-managed-deployments/upgrading/materialize-instances/v1.md
@@ -1,20 +1,20 @@
 ---
-title: "v1alpha2"
-description: "Upgrading Self-Managed Materialize instances using the v1alpha2 CRD API (v26.19+)."
+title: "v1"
+description: "Upgrading Self-Managed Materialize instances using the v1 CRD API (v26.29+)."
 menu:
   main:
     parent: "upgrading-materialize-instances"
-    identifier: "upgrading-v1alpha2"
+    identifier: "upgrading-v1"
     weight: 10
 ---
 
 {{< note >}}
-If you are currently using v1alpha1 and want to switch, see [Switching from v1alpha1 to v1alpha2](/self-managed-deployments/upgrading/materialize-instances/#switching-from-v1alpha1-to-v1alpha2).
+If you are currently using v1alpha1 and want to switch, see [Switching from v1alpha1 to v1](/self-managed-deployments/upgrading/materialize-instances/#switching-from-v1alpha1-to-v1).
 {{</ note >}}
 
 ## Upgrading Materialize Instances
 
-With the `v1alpha2` CRD, rollouts trigger automatically when spec fields change.
+With the `v1` CRD, rollouts trigger automatically when spec fields change.
 Unlike `v1alpha1`, there is no `requestRollout` field. You only need to update the spec and the operator handles the rest.
 
 **After** you have upgraded your Materialize Operator, upgrade your Materialize
@@ -43,7 +43,7 @@ use the `kubectl patch` command; for example, if the **App Version** is {{< self
 kubectl patch materialize <instance-name> \
   -n <materialize-instance-namespace> \
   --type='merge' \
-  -p "{\"apiVersion\": \"materialize.cloud/v1alpha2\", \"spec\": {\"environmentdImageRef\": \"docker.io/materialize/environmentd:{{< self-managed/versions/get-latest-version >}}\"}}"
+  -p "{\"apiVersion\": \"materialize.cloud/v1\", \"spec\": {\"environmentdImageRef\": \"docker.io/materialize/environmentd:{{< self-managed/versions/get-latest-version >}}\"}}"
 ```
 
 
@@ -52,7 +52,7 @@ kubectl patch materialize <instance-name> \
 Alternatively, you can update your Materialize custom resource definition directly:
 
 ```yaml
-apiVersion: materialize.cloud/v1alpha2
+apiVersion: materialize.cloud/v1
 kind: Materialize
 metadata:
   name: 12345678-1234-1234-1234-123456789012
@@ -80,16 +80,16 @@ update the `environmentd_version` variable:
 module "materialize_instance" {
   source = "../kubernetes/modules/materialize-instance"
 
-  crd_version        = "v1alpha2"
+  crd_version        = "v1"
   request_rollout    = null
-  environmentd_version = "v26.19.0"  # Update to the new version
+  environmentd_version = "v26.29.0"  # Update to the new version
   # ... other configuration
 }
 ```
 
 ## Rollout Configuration
 
-With `v1alpha2`, the operator computes a hash of the spec fields and automatically triggers a rollout when the hash changes. The `requestRollout` field from `v1alpha1` is not used.
+With `v1`, the operator computes a hash of the spec fields and automatically triggers a rollout when the hash changes. The `requestRollout` field from `v1alpha1` is not used.
 
 #### `forceRollout`
 
@@ -101,7 +101,7 @@ hash calculation, so changing it produces a new hash and triggers a rollout.
 kubectl patch materialize <instance-name> \
   -n materialize-environment \
   --type='merge' \
-  -p "{\"apiVersion\": \"materialize.cloud/v1alpha2\", \"spec\": {\"forceRollout\": \"$(uuidgen)\"}}"
+  -p "{\"apiVersion\": \"materialize.cloud/v1\", \"spec\": {\"forceRollout\": \"$(uuidgen)\"}}"
 ```
 
 ### Rollout strategies
diff --git a/doc/user/content/self-managed-deployments/upgrading/materialize-instances/v1alpha1.md b/doc/user/content/self-managed-deployments/upgrading/materialize-instances/v1alpha1.md
@@ -1,6 +1,6 @@
 ---
 title: "v1alpha1"
-description: "Upgrading Self-Managed Materialize instances using the v1alpha1 CRD API (before v26.19)."
+description: "Upgrading Self-Managed Materialize instances using the v1alpha1 CRD API (before v26.29)."
 menu:
   main:
     parent: "upgrading-materialize-instances"
@@ -192,17 +192,26 @@ kubectl logs -l app.kubernetes.io/name=materialize-operator -n materialize
 
 You may want to cancel an in-progress rollout if the upgrade has failed. This may be indicated by new pods not being 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.
 
-To cancel an in-progress rollout and revert to the last completed rollout state, first retrieve the last rollout request ID from your Materialize CR:
+To cancel an in-progress rollout and revert to the last completed rollout
+state, revert both `requestRollout` and `environmentdImageRef` back to the
+values from the last completed rollout. Reverting `environmentdImageRef`
+alongside `requestRollout` keeps the spec aligned with what is actually
+running, so a later rollout doesn't accidentally pick up the previously
+attempted upgrade image.
+
+First, retrieve the last completed rollout request ID and the matching
+environmentd image ref from your Materialize CR:
 
 ```shell
-kubectl get materialize <instance-name> -n materialize-environment -o jsonpath='{.status.lastCompletedRolloutRequest}'
+kubectl get materialize <instance-name> -n materialize-environment \
+  -o jsonpath='{.status.lastCompletedRolloutRequest} {.status.lastCompletedRolloutEnvironmentdImageRef}'
 ```
 
-Then, set the `requestRollout` back to this value:
+Then, set both fields back to these values in a single patch:
 
 ```shell
 kubectl patch materialize <instance-name> \
   -n materialize-environment \
   --type='merge' \
-  -p "{\"spec\": {\"requestRollout\": \"<lastCompletedRolloutRequest-value>\"}}"
+  -p "{\"spec\": {\"requestRollout\": \"<lastCompletedRolloutRequest-value>\", \"environmentdImageRef\": \"<lastCompletedRolloutEnvironmentdImageRef-value>\"}}"
 ```
diff --git a/doc/user/data/self_managed/materialize_crd_descriptions_v1.json b/doc/user/data/self_managed/materialize_crd_descriptions_v1.json
diff --git a/doc/user/layouts/shortcodes/self-managed/materialize-crd-descriptions-v1.html b/doc/user/layouts/shortcodes/self-managed/materialize-crd-descriptions-v1.html
diff --git a/doc/user/layouts/shortcodes/self-managed/versions/upgrade/upgrade-steps-local-kind.html b/doc/user/layouts/shortcodes/self-managed/versions/upgrade/upgrade-steps-local-kind.html
diff --git a/doc/user/shared-content/self-managed/upgrade-notes/v26.0.md b/doc/user/shared-content/self-managed/upgrade-notes/v26.0.md
diff --git a/doc/user/shared-content/self-managed/upgrade-notes/v26.29.md b/doc/user/shared-content/self-managed/upgrade-notes/v26.29.md
diff --git a/src/cloud-resources/src/bin/crd_writer.rs b/src/cloud-resources/src/bin/crd_writer.rs
