Skip to content

Commit f317ff0

Browse files
alex-hunt-materializeclaude
alex-hunt-materialize
and
claude
committed
docs: address v1 CRD review feedback and consolidate upgrade instructions
Addresses the latest review round (Val, Kay, def-) on #35508. Correctness fixes: - Rollout hash covers a subset of spec fields (not the whole spec); document which fields are included/excluded (balancerd/console reconcile in place). - Note that adopting v1 on an existing v1alpha1 instance typically triggers one rollout (the hash-derived requestRollout differs from the prior hand-set one). - Fix ManuallyPromote/forcePromote guidance: forcePromote matches status.requestedRolloutHash in v1, requestRollout in v1alpha1. Fixed in the shared MaterializeRolloutStrategy doc comment and regenerated the CRD description JSON for both versions. - Drop the kubectl-patch-apiVersion "switch" example (a no-op; the stored version stays v1alpha1) in favor of full applies. - Use `terraform init` instead of `terraform init -upgrade` to avoid bumping unrelated providers/modules. Restructure: - Consolidate the per-version Upgrading Materialize Instances pages back onto the Upgrading landing page (concepts: adopting v1, rollout configuration, rollout strategies, verifying, cancelling) and into the per-environment guides (Kind, AWS, Azure, GCP), matching main's structure. Delete the v1/v1alpha1 instance subpages and repoint all inbound links to the landing anchors. Consistency: - Reorder/relabel all v1alpha1/v1 tabs (v1alpha1 first, no version parentheses) and factor the repeated blurb into a shared partial/shortcode. - Add optional v1-enablement tabs to the Kind install and the operator-upgrade step (Kind + cloud guides); make cert-manager a regular Kind install step. - Bump hardcoded image versions to the version shortcode; rename the "switching" section to "Adopting the v1 CRD". Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
1 parent 05ccb69 commit f317ff0

23 files changed

Lines changed: 571 additions & 563 deletions

File tree

‎doc/user/content/releases/_index.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1204,7 +1204,7 @@ v26.4.0 introduces several performance improvements and bugfixes.
12041204
- **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.
12051205
- **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.
12061206
- **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.
1207-
- **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.
1207+
- **Manual Promotion** (<red>*Materialize Self-Managed only*</red>): [Rollout strategies](/self-managed-deployments/upgrading/#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.
12081208

12091209
### Bug Fixes {#v26.4-bug-fixes}
12101210
- Fixed timestamp determination logic to handle empty read holds correctly.
@@ -1373,7 +1373,7 @@ use the new setting `rolloutStrategy` to specify either:
13731373
- `WaitUntilReady` (*Default*)
13741374
- `ImmediatelyPromoteCausingDowntime`
13751375

1376-
For more information, see [`rolloutStrategy`](/self-managed-deployments/upgrading/materialize-instances/v1/#rollout-strategies).
1376+
For more information, see [`rolloutStrategy`](/self-managed-deployments/upgrading/#rollout-strategies).
13771377

13781378
### Terraform helpers
13791379

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

Lines changed: 22 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,9 @@ The following example Kubernetes manifest includes configuration for
5151
SASL/SCRAM-SHA-256 authentication:
5252

5353
{{< tabs >}}
54-
{{< tab "v1 (v26.30+)" >}}
54+
{{< tab "v1alpha1" >}}
55+
56+
{{< self-managed/crd-version-note "v1alpha1" >}}
5557

5658
```hc {hl_lines="15 25"}
5759
apiVersion: v1
@@ -70,19 +72,22 @@ stringData:
7072
license_key: "..."
7173
external_login_password_mz_system: "enter_mz_system_password"
7274
---
73-
apiVersion: materialize.cloud/v1
75+
apiVersion: materialize.cloud/v1alpha1
7476
kind: Materialize
7577
metadata:
7678
name: 12345678-1234-1234-1234-123456789012
7779
namespace: materialize-environment
7880
spec:
79-
environmentdImageRef: materialize/environmentd:v26.12.1
81+
environmentdImageRef: materialize/environmentd:{{< self-managed/versions/get-latest-version >}}
8082
backendSecretName: materialize-backend
8183
authenticatorKind: Sasl
84+
requestRollout: 00000000-0000-0000-0000-000000000003 # Enabling auth on an existing instance requires a rollout
8285
```
8386

8487
{{< /tab >}}
85-
{{< tab "v1alpha1 (before v26.30)" >}}
88+
{{< tab "v1" >}}
89+
90+
{{< self-managed/crd-version-note "v1" >}}
8691

8792
```hc {hl_lines="15 25"}
8893
apiVersion: v1
@@ -101,13 +106,13 @@ stringData:
101106
license_key: "..."
102107
external_login_password_mz_system: "enter_mz_system_password"
103108
---
104-
apiVersion: materialize.cloud/v1alpha1
109+
apiVersion: materialize.cloud/v1
105110
kind: Materialize
106111
metadata:
107112
name: 12345678-1234-1234-1234-123456789012
108113
namespace: materialize-environment
109114
spec:
110-
environmentdImageRef: materialize/environmentd:v26.12.1
115+
environmentdImageRef: materialize/environmentd:{{< self-managed/versions/get-latest-version >}}
111116
backendSecretName: materialize-backend
112117
authenticatorKind: Sasl
113118
```
@@ -135,7 +140,9 @@ The following example Kubernetes manifest includes configuration for password
135140
authentication:
136141

137142
{{< tabs >}}
138-
{{< tab "v1 (v26.30+)" >}}
143+
{{< tab "v1alpha1" >}}
144+
145+
{{< self-managed/crd-version-note "v1alpha1" >}}
139146

140147
```hc {hl_lines="15 25"}
141148
apiVersion: v1
@@ -154,19 +161,22 @@ stringData:
154161
license_key: "..."
155162
external_login_password_mz_system: "enter_mz_system_password"
156163
---
157-
apiVersion: materialize.cloud/v1
164+
apiVersion: materialize.cloud/v1alpha1
158165
kind: Materialize
159166
metadata:
160167
name: 12345678-1234-1234-1234-123456789012
161168
namespace: materialize-environment
162169
spec:
163-
environmentdImageRef: materialize/environmentd:v26.12.1
170+
environmentdImageRef: materialize/environmentd:{{< self-managed/versions/get-latest-version >}}
164171
backendSecretName: materialize-backend
165172
authenticatorKind: Password
173+
requestRollout: 00000000-0000-0000-0000-000000000003 # Enabling auth on an existing instance requires a rollout
166174
```
167175

168176
{{< /tab >}}
169-
{{< tab "v1alpha1 (before v26.30)" >}}
177+
{{< tab "v1" >}}
178+
179+
{{< self-managed/crd-version-note "v1" >}}
170180

171181
```hc {hl_lines="15 25"}
172182
apiVersion: v1
@@ -185,13 +195,13 @@ stringData:
185195
license_key: "..."
186196
external_login_password_mz_system: "enter_mz_system_password"
187197
---
188-
apiVersion: materialize.cloud/v1alpha1
198+
apiVersion: materialize.cloud/v1
189199
kind: Materialize
190200
metadata:
191201
name: 12345678-1234-1234-1234-123456789012
192202
namespace: materialize-environment
193203
spec:
194-
environmentdImageRef: materialize/environmentd:v26.12.1
204+
environmentdImageRef: materialize/environmentd:{{< self-managed/versions/get-latest-version >}}
195205
backendSecretName: materialize-backend
196206
authenticatorKind: Password
197207
```

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

Lines changed: 61 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -212,6 +212,11 @@ following fields:
212212
The following example Kubernetes manifest includes configuration for OIDC
213213
authentication:
214214

215+
{{< tabs >}}
216+
{{< tab "v1alpha1" >}}
217+
218+
{{< self-managed/crd-version-note "v1alpha1" >}}
219+
215220
```yaml {hl_lines="6-15 26 36-38"}
216221
apiVersion: v1
217222
kind: Namespace
@@ -246,17 +251,71 @@ metadata:
246251
name: 12345678-1234-1234-1234-123456789012
247252
namespace: materialize-environment
248253
spec:
249-
environmentdImageRef: materialize/environmentd:v26.26.0 # Use v26.26.0 or later
254+
environmentdImageRef: materialize/environmentd:{{< self-managed/versions/get-latest-version >}}
250255
backendSecretName: materialize-backend
251256
authenticatorKind: Oidc
252257
requestRollout: 00000000-0000-0000-0000-000000000003 # Switching to Oidc requires a rollout
253258
systemParameterConfigmapName: mz-system-params # Adding a system parameter configmap requires a rollout
254259
```
255260
256261
Apply the updated manifest to your Kubernetes cluster. See
257-
[Upgrading](/self-managed-deployments/upgrading/materialize-instances/v1alpha1/#rollout-configuration) for
262+
[Upgrading](/self-managed-deployments/upgrading/#rollout-configuration) for
258263
details on rollout configuration.
259264
265+
{{< /tab >}}
266+
{{< tab "v1" >}}
267+
268+
{{< self-managed/crd-version-note "v1" >}}
269+
270+
```yaml {hl_lines="6-15 26 36-37"}
271+
apiVersion: v1
272+
kind: Namespace
273+
metadata:
274+
name: materialize-environment
275+
---
276+
apiVersion: v1
277+
kind: ConfigMap
278+
metadata:
279+
name: mz-system-params
280+
namespace: materialize-environment
281+
data:
282+
# Create an empty system parameter configmap for later steps
283+
system-params.json: |
284+
{
285+
}
286+
---
287+
apiVersion: v1
288+
kind: Secret
289+
metadata:
290+
name: materialize-backend
291+
namespace: materialize-environment
292+
stringData:
293+
metadata_backend_url: "..."
294+
persist_backend_url: "..."
295+
license_key: "..."
296+
external_login_password_mz_system: "enter_mz_system_password"
297+
---
298+
apiVersion: materialize.cloud/v1
299+
kind: Materialize
300+
metadata:
301+
name: 12345678-1234-1234-1234-123456789012
302+
namespace: materialize-environment
303+
spec:
304+
environmentdImageRef: materialize/environmentd:{{< self-managed/versions/get-latest-version >}}
305+
backendSecretName: materialize-backend
306+
authenticatorKind: Oidc
307+
systemParameterConfigmapName: mz-system-params
308+
```
309+
310+
Apply the updated manifest to your Kubernetes cluster. With the `v1` CRD,
311+
rollouts trigger automatically when spec fields change, so no `requestRollout`
312+
is needed. See
313+
[Upgrading](/self-managed-deployments/upgrading/#rollout-configuration)
314+
for details on rollout configuration.
315+
316+
{{< /tab >}}
317+
{{< /tabs >}}
318+
260319
{{% include-headless
261320
"/headless/self-managed-deployments/enabled-auth-setting-warning" %}}
262321

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

Lines changed: 18 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -158,10 +158,12 @@ Materialize CR, see [Materialize CRD Field
158158
Descriptions](/self-managed-deployments/materialize-crd-field-descriptions/).
159159

160160
{{< tabs >}}
161-
{{< tab "v1 (v26.30+)" >}}
161+
{{< tab "v1alpha1" >}}
162+
163+
{{< self-managed/crd-version-note "v1alpha1" >}}
162164

163165
```yaml
164-
apiVersion: materialize.cloud/v1
166+
apiVersion: materialize.cloud/v1alpha1
165167
kind: Materialize
166168
metadata:
167169
name: 12345678-1234-1234-1234-123456789012
@@ -172,10 +174,12 @@ spec:
172174
```
173175

174176
{{< /tab >}}
175-
{{< tab "v1alpha1 (before v26.30)" >}}
177+
{{< tab "v1" >}}
178+
179+
{{< self-managed/crd-version-note "v1" >}}
176180

177181
```yaml
178-
apiVersion: materialize.cloud/v1alpha1
182+
apiVersion: materialize.cloud/v1
179183
kind: Materialize
180184
metadata:
181185
name: 12345678-1234-1234-1234-123456789012
@@ -194,13 +198,9 @@ creates all required Kubernetes resources.
194198
#### Modifying the custom resource
195199

196200
{{< tabs >}}
197-
{{< tab "v1 (v26.30+)" >}}
198-
199-
To modify a custom resource, update the CRD with your changes.
200-
When you apply the CRD, the operator will roll out the changes.
201+
{{< tab "v1alpha1" >}}
201202

202-
{{< /tab >}}
203-
{{< tab "v1alpha1 (before v26.30)" >}}
203+
{{< self-managed/crd-version-note "v1alpha1" >}}
204204

205205
To modify a custom resource, update the CRD with your changes, including the
206206
`requestRollout` field with a new UUID value. When you apply the CRD, the
@@ -211,6 +211,14 @@ If you do not specify a new `requestRollout` UUID, the operator
211211
watches for updates but does not roll out the changes.
212212
{{< /note >}}
213213

214+
{{< /tab >}}
215+
{{< tab "v1" >}}
216+
217+
{{< self-managed/crd-version-note "v1" >}}
218+
219+
To modify a custom resource, update the CRD with your changes.
220+
When you apply the CRD, the operator will roll out the changes.
221+
214222
{{< /tab >}}
215223
{{< /tabs >}}
216224

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

Lines changed: 21 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -68,34 +68,38 @@ Reference the ConfigMap in your Materialize custom resource by setting the
6868
`systemParameterConfigmapName` field to the name of your ConfigMap:
6969

7070
{{< tabs >}}
71-
{{< tab "v1 (v26.30+)" >}}
71+
{{< tab "v1alpha1" >}}
7272

73-
```yaml {hl_lines="9"}
74-
apiVersion: materialize.cloud/v1
73+
{{< self-managed/crd-version-note "v1alpha1" >}}
74+
75+
```yaml {hl_lines="9-10"}
76+
apiVersion: materialize.cloud/v1alpha1
7577
kind: Materialize
7678
metadata:
7779
name: 12345678-1234-1234-1234-123456789012
7880
namespace: materialize-environment
7981
spec:
80-
environmentdImageRef: materialize/environmentd:v26.0.0
82+
environmentdImageRef: materialize/environmentd:{{< self-managed/versions/get-latest-version >}}
8183
backendSecretName: materialize-backend
8284
systemParameterConfigmapName: mz-system-params
85+
requestRollout: 00000000-0000-0000-0000-000000000003 # Changing the CR requires a rollout
8386
```
8487
8588
{{< /tab >}}
86-
{{< tab "v1alpha1 (before v26.30)" >}}
89+
{{< tab "v1" >}}
8790
88-
```yaml {hl_lines="9-10"}
89-
apiVersion: materialize.cloud/v1alpha1
91+
{{< self-managed/crd-version-note "v1" >}}
92+
93+
```yaml {hl_lines="9"}
94+
apiVersion: materialize.cloud/v1
9095
kind: Materialize
9196
metadata:
9297
name: 12345678-1234-1234-1234-123456789012
9398
namespace: materialize-environment
9499
spec:
95-
environmentdImageRef: materialize/environmentd:v26.0.0
100+
environmentdImageRef: materialize/environmentd:{{< self-managed/versions/get-latest-version >}}
96101
backendSecretName: materialize-backend
97102
systemParameterConfigmapName: mz-system-params
98-
requestRollout: 00000000-0000-0000-0000-000000000003 # Changing the CR requires a rollout
99103
```
100104
101105
{{< /tab >}}
@@ -151,10 +155,12 @@ Materialize custom resource YAML and update it whenever you need to force a
151155
ConfigMap reload:
152156

153157
{{< tabs >}}
154-
{{< tab "v1 (v26.30+)" >}}
158+
{{< tab "v1alpha1" >}}
159+
160+
{{< self-managed/crd-version-note "v1alpha1" >}}
155161

156162
```yaml
157-
apiVersion: materialize.cloud/v1
163+
apiVersion: materialize.cloud/v1alpha1
158164
kind: Materialize
159165
metadata:
160166
name: 12345678-1234-1234-1234-123456789012
@@ -166,10 +172,12 @@ spec:
166172
```
167173

168174
{{< /tab >}}
169-
{{< tab "v1alpha1 (before v26.30)" >}}
175+
{{< tab "v1" >}}
176+
177+
{{< self-managed/crd-version-note "v1" >}}
170178

171179
```yaml
172-
apiVersion: materialize.cloud/v1alpha1
180+
apiVersion: materialize.cloud/v1
173181
kind: Materialize
174182
metadata:
175183
name: 12345678-1234-1234-1234-123456789012

‎doc/user/content/self-managed-deployments/installation/install-on-local-kind.md‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -107,7 +107,7 @@ Starting in v26.0, Self-Managed Materialize requires a license key.
107107
kubectl get nodes --show-labels
108108
```
109109

110-
1. Recommended: Install cert-manager
110+
1. Install cert-manager
111111

112112
Cert-manager is used for generating TLS certificates needed by the materialize operator
113113
for CRD conversion webhooks. It is currently only required if you enable the v1
@@ -287,6 +287,14 @@ Starting in v26.0, Self-Managed Materialize requires a license key.
287287
kubectl apply -f sample-materialize.yaml
288288
```
289289
290+
{{< tip >}}
291+
**Optional — use the `v1` CRD.** If you enabled the `v1` CRD on the
292+
operator, edit `sample-materialize.yaml` to set `apiVersion:
293+
materialize.cloud/v1` and remove any `requestRollout` field before
294+
applying. See [Adopting the v1
295+
CRD](/self-managed-deployments/upgrading/#adopting-the-v1-crd).
296+
{{< /tip >}}
297+
290298
1. Verify the installation and check the status:
291299
292300
{{< note >}}

‎doc/user/content/self-managed-deployments/materialize-crd-field-descriptions/_index.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,5 +13,5 @@ aliases:
1313

1414
Select the CRD API version for your Materialize deployment:
1515

16-
- [v1 (v26.30+)](/self-managed-deployments/materialize-crd-field-descriptions/v1/)
16+
- [v1 (available starting v26.30+)](/self-managed-deployments/materialize-crd-field-descriptions/v1/)
1717
- [v1alpha1 (before v26.30)](/self-managed-deployments/materialize-crd-field-descriptions/v1alpha1/)

‎doc/user/content/self-managed-deployments/materialize-crd-field-descriptions/v1.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,4 +7,11 @@ menu:
77
weight: 10
88
---
99

10+
{{< note >}}
11+
The `v1` CRD is available starting in v26.30 and is opt-in. To get the new
12+
automatic-rollout behavior for an existing instance, see [Adopting the v1
13+
CRD](/self-managed-deployments/upgrading/#adopting-the-v1-crd).
14+
For the earlier API, see [v1alpha1](/self-managed-deployments/materialize-crd-field-descriptions/v1alpha1/).
15+
{{</ note >}}
16+
1017
{{% self-managed/materialize-crd-descriptions-v1 %}}

0 commit comments

Comments
 (0)