docs: document the v1 Materialize CRD and installV1CRD opt-in

bin/bump-version

@@ -70,9 +70,11 @@ rm -f src/{clusterd,environmentd,materialized,persist-client,testdrive,catalog-d
 
 cargo update --workspace
 
-crd_descriptions_json=doc/user/data/self_managed/materialize_crd_descriptions.json
-cargo run -p mz-cloud-resources --bin crd-writer > "${crd_descriptions_json}"
-git add "${crd_descriptions_json}"
+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}"
+done
 
 bin/helm-chart-version-bump --bump-orchestratord-version "v$version"
 

doc/user/content/releases/_index.md

@@ -1422,8 +1422,8 @@ See also Upgrade Notes for release specific notes.
 
 {{< include-md file="shared-content/self-managed/upgrade-notes/v26.0.md" >}}
 
-See also [Version specific upgrade
-notes](/self-managed-deployments/upgrading/#version-specific-upgrade-notes).
+See also [Version-specific upgrade
+notes](/self-managed-deployments/upgrading/version-notes/).
 
 
 ## See also

doc/user/content/security/self-managed/authentication.md

@@ -50,6 +50,11 @@ following fields:
 The following example Kubernetes manifest includes configuration for
 SASL/SCRAM-SHA-256 authentication:
 
+{{< tabs >}}
+{{< tab "v1alpha1" >}}
+
+{{< self-managed/crd-version-note "v1alpha1" >}}
+
 ```hc {hl_lines="15 25"}
 apiVersion: v1
 kind: Namespace
@@ -73,11 +78,48 @@ metadata:
   name: 12345678-1234-1234-1234-123456789012
   namespace: materialize-environment
 spec:
-  environmentdImageRef: materialize/environmentd:v26.12.1
+  environmentdImageRef: materialize/environmentd:{{< self-managed/versions/get-latest-version >}}
   backendSecretName: materialize-backend
   authenticatorKind: Sasl
+  requestRollout: 00000000-0000-0000-0000-000000000003 # Enabling auth on an existing instance requires a rollout
 ```
 
+{{< /tab >}}
+{{< tab "v1" >}}
+
+{{< self-managed/crd-version-note "v1" >}}
+
+```hc {hl_lines="15 25"}
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: materialize-environment
+---
+apiVersion: v1
+kind: Secret
+metadata:
+  name: materialize-backend
+  namespace: materialize-environment
+stringData:
+  metadata_backend_url: "..."
+  persist_backend_url: "..."
+  license_key: "..."
+  external_login_password_mz_system: "enter_mz_system_password"
+---
+apiVersion: materialize.cloud/v1
+kind: Materialize
+metadata:
+  name: 12345678-1234-1234-1234-123456789012
+  namespace: materialize-environment
+spec:
+  environmentdImageRef: materialize/environmentd:{{< self-managed/versions/get-latest-version >}}
+  backendSecretName: materialize-backend
+  authenticatorKind: Sasl
+```
+
+{{< /tab >}}
+{{< /tabs >}}
+
 {{% include-headless
 "/headless/self-managed-deployments/enabled-auth-setting-warning" %}}
 
@@ -97,6 +139,11 @@ To configure Self-Managed Materialize for password authentication, update the fo
 The following example Kubernetes manifest includes configuration for password
 authentication:
 
+{{< tabs >}}
+{{< tab "v1alpha1" >}}
+
+{{< self-managed/crd-version-note "v1alpha1" >}}
+
 ```hc {hl_lines="15 25"}
 apiVersion: v1
 kind: Namespace
@@ -120,11 +167,48 @@ metadata:
   name: 12345678-1234-1234-1234-123456789012
   namespace: materialize-environment
 spec:
-  environmentdImageRef: materialize/environmentd:v26.12.1
+  environmentdImageRef: materialize/environmentd:{{< self-managed/versions/get-latest-version >}}
   backendSecretName: materialize-backend
   authenticatorKind: Password
+  requestRollout: 00000000-0000-0000-0000-000000000003 # Enabling auth on an existing instance requires a rollout
 ```
 
+{{< /tab >}}
+{{< tab "v1" >}}
+
+{{< self-managed/crd-version-note "v1" >}}
+
+```hc {hl_lines="15 25"}
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: materialize-environment
+---
+apiVersion: v1
+kind: Secret
+metadata:
+  name: materialize-backend
+  namespace: materialize-environment
+stringData:
+  metadata_backend_url: "..."
+  persist_backend_url: "..."
+  license_key: "..."
+  external_login_password_mz_system: "enter_mz_system_password"
+---
+apiVersion: materialize.cloud/v1
+kind: Materialize
+metadata:
+  name: 12345678-1234-1234-1234-123456789012
+  namespace: materialize-environment
+spec:
+  environmentdImageRef: materialize/environmentd:{{< self-managed/versions/get-latest-version >}}
+  backendSecretName: materialize-backend
+  authenticatorKind: Password
+```
+
+{{< /tab >}}
+{{< /tabs >}}
+
 {{% include-headless
 "/headless/self-managed-deployments/enabled-auth-setting-warning" %}}
 

doc/user/content/security/self-managed/sso.md

@@ -212,6 +212,11 @@ following fields:
 The following example Kubernetes manifest includes configuration for OIDC
 authentication:
 
+{{< tabs >}}
+{{< tab "v1alpha1" >}}
+
+{{< self-managed/crd-version-note "v1alpha1" >}}
+
 ```yaml {hl_lines="6-15 26 36-38"}
 apiVersion: v1
 kind: Namespace
@@ -246,7 +251,7 @@ metadata:
   name: 12345678-1234-1234-1234-123456789012
   namespace: materialize-environment
 spec:
-  environmentdImageRef: materialize/environmentd:v26.26.0 # Use v26.26.0 or later
+  environmentdImageRef: materialize/environmentd:{{< self-managed/versions/get-latest-version >}}
   backendSecretName: materialize-backend
   authenticatorKind: Oidc
   requestRollout: 00000000-0000-0000-0000-000000000003 # Switching to Oidc requires a rollout
@@ -257,6 +262,60 @@ Apply the updated manifest to your Kubernetes cluster. See
 [Upgrading](/self-managed-deployments/upgrading/#rollout-configuration) for
 details on rollout configuration.
 
+{{< /tab >}}
+{{< tab "v1" >}}
+
+{{< self-managed/crd-version-note "v1" >}}
+
+```yaml {hl_lines="6-15 26 36-37"}
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: materialize-environment
+---
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: mz-system-params
+  namespace: materialize-environment
+data:
+  # Create an empty system parameter configmap for later steps
+  system-params.json: |
+    {
+    }
+---
+apiVersion: v1
+kind: Secret
+metadata:
+  name: materialize-backend
+  namespace: materialize-environment
+stringData:
+  metadata_backend_url: "..."
+  persist_backend_url: "..."
+  license_key: "..."
+  external_login_password_mz_system: "enter_mz_system_password"
+---
+apiVersion: materialize.cloud/v1
+kind: Materialize
+metadata:
+  name: 12345678-1234-1234-1234-123456789012
+  namespace: materialize-environment
+spec:
+  environmentdImageRef: materialize/environmentd:{{< self-managed/versions/get-latest-version >}}
+  backendSecretName: materialize-backend
+  authenticatorKind: Oidc
+  systemParameterConfigmapName: mz-system-params
+```
+
+Apply the updated manifest to your Kubernetes cluster. With the `v1` CRD,
+rollouts trigger automatically when spec fields change, so no `requestRollout`
+is needed. See
+[Upgrading](/self-managed-deployments/upgrading/#rollout-configuration)
+for details on rollout configuration.
+
+{{< /tab >}}
+{{< /tabs >}}
+
 {{% include-headless
 "/headless/self-managed-deployments/enabled-auth-setting-warning" %}}
 

doc/user/content/self-managed-deployments/_index.md

@@ -157,6 +157,11 @@ custom resource definitions(CRDs). For a full list of fields available for the
 Materialize CR, see [Materialize CRD Field
 Descriptions](/self-managed-deployments/materialize-crd-field-descriptions/).
 
+{{< tabs >}}
+{{< tab "v1alpha1" >}}
+
+{{< self-managed/crd-version-note "v1alpha1" >}}
+
 ```yaml
 apiVersion: materialize.cloud/v1alpha1
 kind: Materialize
@@ -168,11 +173,35 @@ spec:
 # ... additional fields omitted for brevity
 ```
 
+{{< /tab >}}
+{{< tab "v1" >}}
+
+{{< self-managed/crd-version-note "v1" >}}
+
+```yaml
+apiVersion: materialize.cloud/v1
+kind: Materialize
+metadata:
+  name: 12345678-1234-1234-1234-123456789012
+  namespace: materialize-environment
+spec:
+  environmentdImageRef: materialize/environmentd:{{< self-managed/versions/get-latest-version >}}
+# ... additional fields omitted for brevity
+```
+
+{{< /tab >}}
+{{< /tabs >}}
+
 When you first apply the Materialize custom resource, the operator automatically
 creates all required Kubernetes resources.
 
 #### Modifying the custom resource
 
+{{< tabs >}}
+{{< tab "v1alpha1" >}}
+
+{{< self-managed/crd-version-note "v1alpha1" >}}
+
 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
 operator will roll out the changes.
@@ -182,6 +211,17 @@ If you do not specify a new `requestRollout` UUID, the operator
 watches for updates but does not roll out the changes.
 {{< /note >}}
 
+{{< /tab >}}
+{{< tab "v1" >}}
+
+{{< self-managed/crd-version-note "v1" >}}
+
+To modify a custom resource, update the CRD with your changes.
+When you apply the CRD, the operator will roll out the changes.
+
+{{< /tab >}}
+{{< /tabs >}}
+
 For a full list of fields available for the Materialize CR, see [Materialize CRD
 Field
 Descriptions](/self-managed-deployments/materialize-crd-field-descriptions/).

doc/user/content/self-managed-deployments/configuration-system-parameters.md

@@ -67,19 +67,44 @@ kubectl apply -f system-params-configmap.yaml
 Reference the ConfigMap in your Materialize custom resource by setting the
 `systemParameterConfigmapName` field to the name of your ConfigMap:
 
+{{< tabs >}}
+{{< tab "v1alpha1" >}}
+
+{{< self-managed/crd-version-note "v1alpha1" >}}
+
 ```yaml {hl_lines="9-10"}
 apiVersion: materialize.cloud/v1alpha1
 kind: Materialize
 metadata:
   name: 12345678-1234-1234-1234-123456789012
   namespace: materialize-environment
 spec:
-  environmentdImageRef: materialize/environmentd:v26.0.0
+  environmentdImageRef: materialize/environmentd:{{< self-managed/versions/get-latest-version >}}
   backendSecretName: materialize-backend
   systemParameterConfigmapName: mz-system-params
   requestRollout: 00000000-0000-0000-0000-000000000003 # Changing the CR requires a rollout
 ```
 
+{{< /tab >}}
+{{< tab "v1" >}}
+
+{{< self-managed/crd-version-note "v1" >}}
+
+```yaml {hl_lines="9"}
+apiVersion: materialize.cloud/v1
+kind: Materialize
+metadata:
+  name: 12345678-1234-1234-1234-123456789012
+  namespace: materialize-environment
+spec:
+  environmentdImageRef: materialize/environmentd:{{< self-managed/versions/get-latest-version >}}
+  backendSecretName: materialize-backend
+  systemParameterConfigmapName: mz-system-params
+```
+
+{{< /tab >}}
+{{< /tabs >}}
+
 Apply the updated Materialize resource:
 
 ```shell
@@ -129,6 +154,11 @@ Alternatively, you can add the `configmap-reload-trigger` annotation to your
 Materialize custom resource YAML and update it whenever you need to force a
 ConfigMap reload:
 
+{{< tabs >}}
+{{< tab "v1alpha1" >}}
+
+{{< self-managed/crd-version-note "v1alpha1" >}}
+
 ```yaml
 apiVersion: materialize.cloud/v1alpha1
 kind: Materialize
@@ -141,6 +171,26 @@ spec:
   # ... rest of spec
 ```
 
+{{< /tab >}}
+{{< tab "v1" >}}
+
+{{< self-managed/crd-version-note "v1" >}}
+
+```yaml
+apiVersion: materialize.cloud/v1
+kind: Materialize
+metadata:
+  name: 12345678-1234-1234-1234-123456789012
+  namespace: materialize-environment
+  annotations:
+    configmap-reload-trigger: "1234567890"  # Update this value to force reload
+spec:
+  # ... rest of spec
+```
+
+{{< /tab >}}
+{{< /tabs >}}
+
 {{< note >}}
 Even after the ConfigMap is synced, some system parameters may require a restart to
 take effect.