Skip to content

Commit be46642

Browse files
alex-hunt-materializealex-hunt-materialize
committed
update docs for Materialize CRD v1
1 parent a60b65e commit be46642

22 files changed

Lines changed: 1667 additions & 230 deletions

File tree

‎bin/bump-version‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -70,9 +70,11 @@ rm -f src/{clusterd,environmentd,materialized,persist-client,testdrive,catalog-d
7070

7171
cargo update --workspace
7272

73-
crd_descriptions_json=doc/user/data/self_managed/materialize_crd_descriptions.json
74-
cargo run -p mz-cloud-resources --bin crd-writer > "${crd_descriptions_json}"
75-
git add "${crd_descriptions_json}"
73+
for crd_version in v1alpha1 v1; do
74+
crd_descriptions_json="doc/user/data/self_managed/materialize_crd_descriptions_${crd_version}.json"
75+
cargo run -p mz-cloud-resources --bin crd-writer -- "${crd_version}" > "${crd_descriptions_json}"
76+
git add "${crd_descriptions_json}"
77+
done
7678

7779
bin/helm-chart-version-bump --bump-orchestratord-version "v$version"
7880

‎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/#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/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.
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/#rollout-strategies).
1376+
For more information, see [`rolloutStrategy`](/self-managed-deployments/upgrading/materialize-instances/v1/#rollout-strategies).
13771377

13781378
### Terraform helpers
13791379

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

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -50,6 +50,40 @@ following fields:
5050
The following example Kubernetes manifest includes configuration for
5151
SASL/SCRAM-SHA-256 authentication:
5252

53+
{{< tabs >}}
54+
{{< tab "v1 (v26.30+)" >}}
55+
56+
```hc {hl_lines="15 25"}
57+
apiVersion: v1
58+
kind: Namespace
59+
metadata:
60+
name: materialize-environment
61+
---
62+
apiVersion: v1
63+
kind: Secret
64+
metadata:
65+
name: materialize-backend
66+
namespace: materialize-environment
67+
stringData:
68+
metadata_backend_url: "..."
69+
persist_backend_url: "..."
70+
license_key: "..."
71+
external_login_password_mz_system: "enter_mz_system_password"
72+
---
73+
apiVersion: materialize.cloud/v1
74+
kind: Materialize
75+
metadata:
76+
name: 12345678-1234-1234-1234-123456789012
77+
namespace: materialize-environment
78+
spec:
79+
environmentdImageRef: materialize/environmentd:v26.12.1
80+
backendSecretName: materialize-backend
81+
authenticatorKind: Sasl
82+
```
83+
84+
{{< /tab >}}
85+
{{< tab "v1alpha1 (before v26.30)" >}}
86+
5387
```hc {hl_lines="15 25"}
5488
apiVersion: v1
5589
kind: Namespace
@@ -78,6 +112,9 @@ spec:
78112
authenticatorKind: Sasl
79113
```
80114

115+
{{< /tab >}}
116+
{{< /tabs >}}
117+
81118
{{% include-headless
82119
"/headless/self-managed-deployments/enabled-auth-setting-warning" %}}
83120

@@ -97,6 +134,40 @@ To configure Self-Managed Materialize for password authentication, update the fo
97134
The following example Kubernetes manifest includes configuration for password
98135
authentication:
99136

137+
{{< tabs >}}
138+
{{< tab "v1 (v26.30+)" >}}
139+
140+
```hc {hl_lines="15 25"}
141+
apiVersion: v1
142+
kind: Namespace
143+
metadata:
144+
name: materialize-environment
145+
---
146+
apiVersion: v1
147+
kind: Secret
148+
metadata:
149+
name: materialize-backend
150+
namespace: materialize-environment
151+
stringData:
152+
metadata_backend_url: "..."
153+
persist_backend_url: "..."
154+
license_key: "..."
155+
external_login_password_mz_system: "enter_mz_system_password"
156+
---
157+
apiVersion: materialize.cloud/v1
158+
kind: Materialize
159+
metadata:
160+
name: 12345678-1234-1234-1234-123456789012
161+
namespace: materialize-environment
162+
spec:
163+
environmentdImageRef: materialize/environmentd:v26.12.1
164+
backendSecretName: materialize-backend
165+
authenticatorKind: Password
166+
```
167+
168+
{{< /tab >}}
169+
{{< tab "v1alpha1 (before v26.30)" >}}
170+
100171
```hc {hl_lines="15 25"}
101172
apiVersion: v1
102173
kind: Namespace
@@ -125,6 +196,9 @@ spec:
125196
authenticatorKind: Password
126197
```
127198

199+
{{< /tab >}}
200+
{{< /tabs >}}
201+
128202
{{% include-headless
129203
"/headless/self-managed-deployments/enabled-auth-setting-warning" %}}
130204

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -254,7 +254,7 @@ spec:
254254
```
255255
256256
Apply the updated manifest to your Kubernetes cluster. See
257-
[Upgrading](/self-managed-deployments/upgrading/#rollout-configuration) for
257+
[Upgrading](/self-managed-deployments/upgrading/materialize-instances/v1alpha1/#rollout-configuration) for
258258
details on rollout configuration.
259259
260260
{{% include-headless

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

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -157,6 +157,23 @@ custom resource definitions(CRDs). For a full list of fields available for the
157157
Materialize CR, see [Materialize CRD Field
158158
Descriptions](/self-managed-deployments/materialize-crd-field-descriptions/).
159159

160+
{{< tabs >}}
161+
{{< tab "v1 (v26.30+)" >}}
162+
163+
```yaml
164+
apiVersion: materialize.cloud/v1
165+
kind: Materialize
166+
metadata:
167+
name: 12345678-1234-1234-1234-123456789012
168+
namespace: materialize-environment
169+
spec:
170+
environmentdImageRef: materialize/environmentd:{{< self-managed/versions/get-latest-version >}}
171+
# ... additional fields omitted for brevity
172+
```
173+
174+
{{< /tab >}}
175+
{{< tab "v1alpha1 (before v26.30)" >}}
176+
160177
```yaml
161178
apiVersion: materialize.cloud/v1alpha1
162179
kind: Materialize
@@ -168,11 +185,23 @@ spec:
168185
# ... additional fields omitted for brevity
169186
```
170187

188+
{{< /tab >}}
189+
{{< /tabs >}}
190+
171191
When you first apply the Materialize custom resource, the operator automatically
172192
creates all required Kubernetes resources.
173193

174194
#### Modifying the custom resource
175195

196+
{{< 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+
202+
{{< /tab >}}
203+
{{< tab "v1alpha1 (before v26.30)" >}}
204+
176205
To modify a custom resource, update the CRD with your changes, including the
177206
`requestRollout` field with a new UUID value. When you apply the CRD, the
178207
operator will roll out the changes.
@@ -182,6 +211,9 @@ If you do not specify a new `requestRollout` UUID, the operator
182211
watches for updates but does not roll out the changes.
183212
{{< /note >}}
184213

214+
{{< /tab >}}
215+
{{< /tabs >}}
216+
185217
For a full list of fields available for the Materialize CR, see [Materialize CRD
186218
Field
187219
Descriptions](/self-managed-deployments/materialize-crd-field-descriptions/).

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

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,24 @@ kubectl apply -f system-params-configmap.yaml
6767
Reference the ConfigMap in your Materialize custom resource by setting the
6868
`systemParameterConfigmapName` field to the name of your ConfigMap:
6969

70+
{{< tabs >}}
71+
{{< tab "v1 (v26.30+)" >}}
72+
73+
```yaml {hl_lines="9"}
74+
apiVersion: materialize.cloud/v1
75+
kind: Materialize
76+
metadata:
77+
name: 12345678-1234-1234-1234-123456789012
78+
namespace: materialize-environment
79+
spec:
80+
environmentdImageRef: materialize/environmentd:v26.0.0
81+
backendSecretName: materialize-backend
82+
systemParameterConfigmapName: mz-system-params
83+
```
84+
85+
{{< /tab >}}
86+
{{< tab "v1alpha1 (before v26.30)" >}}
87+
7088
```yaml {hl_lines="9-10"}
7189
apiVersion: materialize.cloud/v1alpha1
7290
kind: Materialize
@@ -80,6 +98,9 @@ spec:
8098
requestRollout: 00000000-0000-0000-0000-000000000003 # Changing the CR requires a rollout
8199
```
82100
101+
{{< /tab >}}
102+
{{< /tabs >}}
103+
83104
Apply the updated Materialize resource:
84105
85106
```shell
@@ -129,6 +150,24 @@ Alternatively, you can add the `configmap-reload-trigger` annotation to your
129150
Materialize custom resource YAML and update it whenever you need to force a
130151
ConfigMap reload:
131152

153+
{{< tabs >}}
154+
{{< tab "v1 (v26.30+)" >}}
155+
156+
```yaml
157+
apiVersion: materialize.cloud/v1
158+
kind: Materialize
159+
metadata:
160+
name: 12345678-1234-1234-1234-123456789012
161+
namespace: materialize-environment
162+
annotations:
163+
configmap-reload-trigger: "1234567890" # Update this value to force reload
164+
spec:
165+
# ... rest of spec
166+
```
167+
168+
{{< /tab >}}
169+
{{< tab "v1alpha1 (before v26.30)" >}}
170+
132171
```yaml
133172
apiVersion: materialize.cloud/v1alpha1
134173
kind: Materialize
@@ -141,6 +180,9 @@ spec:
141180
# ... rest of spec
142181
```
143182

183+
{{< /tab >}}
184+
{{< /tabs >}}
185+
144186
{{< note >}}
145187
Even after the ConfigMap is synced, some system parameters may require a restart to
146188
take effect.

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

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
---
22
title: "Materialize CRD Field Descriptions"
33
description: "Reference page on Materialize CRD Fields"
4+
disable_list: true
45
menu:
56
main:
67
parent: "sm-deployments"
@@ -10,4 +11,7 @@ aliases:
1011
- /installation/appendix-materialize-crd-field-descriptions/
1112
---
1213

13-
{{% self-managed/materialize-crd-descriptions %}}
14+
Select the CRD API version for your Materialize deployment:
15+
16+
- [v1 (v26.30+)](/self-managed-deployments/materialize-crd-field-descriptions/v1/)
17+
- [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: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
title: "v1"
3+
description: "Reference page on Materialize CRD Fields for the v1 API (v26.30+)"
4+
menu:
5+
main:
6+
parent: "materialize-crd-field-descriptions"
7+
weight: 10
8+
---
9+
10+
{{% self-managed/materialize-crd-descriptions-v1 %}}

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

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
---
2+
title: "v1alpha1"
3+
description: "Reference page on Materialize CRD Fields for the v1alpha1 API (before v26.30)"
4+
menu:
5+
main:
6+
parent: "materialize-crd-field-descriptions"
7+
weight: 20
8+
---
9+
10+
{{% self-managed/materialize-crd-descriptions-v1alpha1 %}}

0 commit comments

Comments
 (0)