Skip to content

Commit d7820a1

Browse files
alex-hunt-materializealex-hunt-materialize
committed
update docs for v1alpha2
1 parent 7714f2e commit d7820a1

21 files changed

Lines changed: 1245 additions & 207 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 v1alpha2; 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
@@ -351,7 +351,7 @@ v26.4.0 introduces several performance improvements and bugfixes.
351351
- **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.
352352
- **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.
353353
- **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.
354-
- **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.
354+
- **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.
355355

356356
### Bug Fixes {#v26.4-bug-fixes}
357357
- Fixed timestamp determination logic to handle empty read holds correctly.
@@ -520,7 +520,7 @@ use the new setting `rolloutStrategy` to specify either:
520520
- `WaitUntilReady` (*Default*)
521521
- `ImmediatelyPromoteCausingDowntime`
522522

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

525525
### Terraform helpers
526526

‎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 "v1alpha2 (v26.16+)" >}}
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/v1alpha2
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.16)" >}}
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 "v1alpha2 (v26.16+)" >}}
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/v1alpha2
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.16)" >}}
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/self-managed-deployments/_index.md‎

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

164+
{{< tabs >}}
165+
{{< tab "v1alpha2 (v26.16+)" >}}
166+
167+
```yaml
168+
apiVersion: materialize.cloud/v1alpha2
169+
kind: Materialize
170+
metadata:
171+
name: 12345678-1234-1234-1234-123456789012
172+
namespace: materialize-environment
173+
spec:
174+
environmentdImageRef: materialize/environmentd:{{< self-managed/versions/get-latest-version >}}
175+
# ... additional fields omitted for brevity
176+
```
177+
178+
{{< /tab >}}
179+
{{< tab "v1alpha1 (before v26.16)" >}}
180+
164181
```yaml
165182
apiVersion: materialize.cloud/v1alpha1
166183
kind: Materialize
@@ -172,11 +189,23 @@ spec:
172189
# ... additional fields omitted for brevity
173190
```
174191

192+
{{< /tab >}}
193+
{{< /tabs >}}
194+
175195
When you first apply the Materialize custom resource, the operator automatically
176196
creates all required Kubernetes resources.
177197

178198
### Modifying the custom resource
179199

200+
{{< tabs >}}
201+
{{< tab "v1alpha2 (v26.16+)" >}}
202+
203+
To modify a custom resource, update the CRD with your changes.
204+
When you apply the CRD, the operator will roll out the changes.
205+
206+
{{< /tab >}}
207+
{{< tab "v1alpha1 (before v26.16)" >}}
208+
180209
To modify a custom resource, update the CRD with your changes, including the
181210
`requestRollout` field with a new UUID value. When you apply the CRD, the
182211
operator will roll out the changes.
@@ -185,6 +214,9 @@ operator will roll out the changes.
185214
watches for updates but does not roll out the changes.
186215
{{< /note >}}
187216

217+
{{< /tab >}}
218+
{{< /tabs >}}
219+
188220
For a full list of fields available for the Materialize CR, see [Materialize CRD
189221
Field
190222
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 "v1alpha2 (v26.16+)" >}}
72+
73+
```yaml {hl_lines="9"}
74+
apiVersion: materialize.cloud/v1alpha2
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.16)" >}}
87+
7088
```yaml {hl_lines="9"}
7189
apiVersion: materialize.cloud/v1alpha1
7290
kind: Materialize
@@ -79,6 +97,9 @@ spec:
7997
systemParameterConfigmapName: mz-system-params
8098
```
8199
100+
{{< /tab >}}
101+
{{< /tabs >}}
102+
82103
Apply the updated Materialize resource:
83104
84105
```shell
@@ -125,6 +146,24 @@ Alternatively, you can add the `configmap-reload-trigger` annotation to your
125146
Materialize custom resource YAML and update it whenever you need to force a
126147
ConfigMap reload:
127148

149+
{{< tabs >}}
150+
{{< tab "v1alpha2 (v26.16+)" >}}
151+
152+
```yaml
153+
apiVersion: materialize.cloud/v1alpha2
154+
kind: Materialize
155+
metadata:
156+
name: 12345678-1234-1234-1234-123456789012
157+
namespace: materialize-environment
158+
annotations:
159+
configmap-reload-trigger: "1234567890" # Update this value to force reload
160+
spec:
161+
# ... rest of spec
162+
```
163+
164+
{{< /tab >}}
165+
{{< tab "v1alpha1 (before v26.16)" >}}
166+
128167
```yaml
129168
apiVersion: materialize.cloud/v1alpha1
130169
kind: Materialize
@@ -137,6 +176,9 @@ spec:
137176
# ... rest of spec
138177
```
139178

179+
{{< /tab >}}
180+
{{< /tabs >}}
181+
140182
{{< note >}}
141183
Even after the ConfigMap is synced, some parameters may require a restart to
142184
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+
- [v1alpha2 (v26.16+)](/self-managed-deployments/materialize-crd-field-descriptions/v1alpha2/)
17+
- [v1alpha1 (before v26.16)](/self-managed-deployments/materialize-crd-field-descriptions/v1alpha1/)

‎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.16)"
4+
menu:
5+
main:
6+
parent: "materialize-crd-field-descriptions"
7+
weight: 20
8+
---
9+
10+
{{% self-managed/materialize-crd-descriptions-v1alpha1 %}}

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

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

0 commit comments

Comments
 (0)