From daae2e9b00cdd3d92aa60a290e44a6efdf2e772f Mon Sep 17 00:00:00 2001 From: Sang Jun Bak Date: Tue, 18 Nov 2025 12:11:17 -0500 Subject: [PATCH 1/3] docs: Add rollout guidance for Self-Managed auth - Removes "kind" references since instructions are generic to the Materialize CR - Adds references to the Materialize CR fields - Adds how to actually deploy authentication with notice about accidentally overriding values. --- .../security/self-managed/authentication.md | 31 +++++++++++++++---- 1 file changed, 25 insertions(+), 6 deletions(-) diff --git a/doc/user/content/security/self-managed/authentication.md b/doc/user/content/security/self-managed/authentication.md index 2647b38e9c7e8..2ebc5e1fa6dd9 100644 --- a/doc/user/content/security/self-managed/authentication.md +++ b/doc/user/content/security/self-managed/authentication.md @@ -26,14 +26,14 @@ used: Password authentication requires users to log in with a password. -To configure Self-Managed Materialize for password authentication: +To configure Self-Managed Materialize for password authentication, update the following fields in the [Materialize CR](/installation/appendix-materialize-crd-field-descriptions/): Configuration | Description ---------------| ------------ `spec.authenticatorKind` | Set to `Password` to enable password authentication. -`external_login_password_mz_system` | To the Kubernetes Secret referenced by `spec.backendSecretName`, add the secret key `external_login_password_mz_system`. This is the password for the `mz_system` user [^1], who is the only user initially available when password authentication is enabled. +`external_login_password_mz_system` | Set to the Kubernetes Secret referenced by `spec.backendSecretName`, add the secret key `external_login_password_mz_system`. This is the password for the `mz_system` user [^1], who is the only user initially available when password authentication is enabled. -For example, if using Kind, in the `sample-materialize.yaml` file: +An example Materialize CR YAML file: ```hc {hl_lines="14 24"} apiVersion: v1 @@ -92,14 +92,14 @@ SASL/SCRAM-SHA-256 authentication is a challenge-response authentication mechani that provides security for **PostgreSQL wire protocol connections**. It is compatible with PostgreSQL clients that support SCRAM-SHA-256. -To configure Self-Managed Materialize for SASL/SCRAM authentication: +To configure Self-Managed Materialize for SASL/SCRAM authentication, update the following fields in the [Materialize CR](/installation/appendix-materialize-crd-field-descriptions/): | Configuration | Description |---------------| ------------ |`spec.authenticatorKind` | Set to `Sasl` to enable SASL/SCRAM-SHA-256 authentication for PostgreSQL connections. -|`external_login_password_mz_system` | To the Kubernetes Secret referenced by `spec.backendSecretName`, add the secret key `external_login_password_mz_system`. This is the password for the `mz_system` user [^1], who is the only user initially available when SASL authentication is enabled. +|`external_login_password_mz_system` | Set to the Kubernetes Secret referenced by `spec.backendSecretName`, add the secret key `external_login_password_mz_system`. This is the password for the `mz_system` user [^1], who is the only user initially available when SASL authentication is enabled. -For example, if using Kind, in the `sample-materialize.yaml` file: +An example Materialize CR YAML file: ```hc {hl_lines="14 24"} apiVersion: v1 @@ -148,6 +148,25 @@ When SASL authentication is enabled: This hybrid approach provides maximum security for SQL connections while maintaining compatibility with web-based tools. +## Deploying authentication + +Using the configured Materialize CR YAML file, we recommend rolling out the changes by adding the following fields: +```yaml +spec: + ... + requestRollout: # Generate new UUID for rollout + forceRollout: # Rollout without requiring a version change + # Tears down the prior version and restarts the current Materialize instance + rolloutStrategy: ImmediatelyPromoteCausingDowntime +``` + +For more information on rollout configuration, view our [installation overview](/installation/#rollout-configuration). + +{{< warning >}} +Ensure that the `authenticatorKind` field is set for any future version upgrades or rollouts of the Materialize CR. Having it undefined will reset `authenticationKind` to `None`. +{{< /warning >}} + + ## Enabling RBAC {{< include-md file="shared-content/enable-rbac.md" >}} From 586e9cdca710afa2c90e70cf79758e953e677d22 Mon Sep 17 00:00:00 2001 From: Sang Jun Bak Date: Wed, 19 Nov 2025 12:49:01 -0500 Subject: [PATCH 2/3] docs: Address review comments - Colocate warning about the `authenticatorKind` with authenticatorKind section - Just reference link to Materialize CR rather than point to it. --- .../content/security/self-managed/authentication.md | 13 +++++++------ doc/user/shared-content/auth-kind-warning.md | 3 +++ 2 files changed, 10 insertions(+), 6 deletions(-) create mode 100644 doc/user/shared-content/auth-kind-warning.md diff --git a/doc/user/content/security/self-managed/authentication.md b/doc/user/content/security/self-managed/authentication.md index 2ebc5e1fa6dd9..614ccdd362896 100644 --- a/doc/user/content/security/self-managed/authentication.md +++ b/doc/user/content/security/self-managed/authentication.md @@ -20,13 +20,17 @@ used: {{% yaml-table data="self_managed/authentication_setting" %}} +{{< include-md file="shared-content/auth-kind-warning.md" >}} + + + ## Configuring password authentication {{< public-preview >}}This feature{{}} Password authentication requires users to log in with a password. -To configure Self-Managed Materialize for password authentication, update the following fields in the [Materialize CR](/installation/appendix-materialize-crd-field-descriptions/): +To configure Self-Managed Materialize for password authentication, update the following fields in the Materialize CR. For all Materialize CR settings, see [here](/installation/appendix-materialize-crd-field-descriptions/). Configuration | Description ---------------| ------------ @@ -92,7 +96,7 @@ SASL/SCRAM-SHA-256 authentication is a challenge-response authentication mechani that provides security for **PostgreSQL wire protocol connections**. It is compatible with PostgreSQL clients that support SCRAM-SHA-256. -To configure Self-Managed Materialize for SASL/SCRAM authentication, update the following fields in the [Materialize CR](/installation/appendix-materialize-crd-field-descriptions/): +To configure Self-Managed Materialize for SASL/SCRAM authentication, update the following fields in the Materialize CR. For all Materialize CR settings, see [here](/installation/appendix-materialize-crd-field-descriptions/). | Configuration | Description |---------------| ------------ @@ -162,10 +166,7 @@ spec: For more information on rollout configuration, view our [installation overview](/installation/#rollout-configuration). -{{< warning >}} -Ensure that the `authenticatorKind` field is set for any future version upgrades or rollouts of the Materialize CR. Having it undefined will reset `authenticationKind` to `None`. -{{< /warning >}} - +{{< include-md file="shared-content/auth-kind-warning.md" >}} ## Enabling RBAC diff --git a/doc/user/shared-content/auth-kind-warning.md b/doc/user/shared-content/auth-kind-warning.md new file mode 100644 index 0000000000000..b95164e91600c --- /dev/null +++ b/doc/user/shared-content/auth-kind-warning.md @@ -0,0 +1,3 @@ +{{< warning >}} +Ensure that the `authenticatorKind` field is set for any future version upgrades or rollouts of the Materialize CR. Having it undefined will reset `authenticationKind` to `None`. +{{< /warning >}} From 0e04e244677fdd52b7a500a809a4dfeea08c2991 Mon Sep 17 00:00:00 2001 From: Sang Jun Bak Date: Tue, 2 Dec 2025 12:13:49 -0500 Subject: [PATCH 3/3] Remove mention of ImmediatelyPromoteWithDowntime --- doc/user/content/security/self-managed/authentication.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/doc/user/content/security/self-managed/authentication.md b/doc/user/content/security/self-managed/authentication.md index 614ccdd362896..5c06c58c16798 100644 --- a/doc/user/content/security/self-managed/authentication.md +++ b/doc/user/content/security/self-managed/authentication.md @@ -160,8 +160,6 @@ spec: ... requestRollout: # Generate new UUID for rollout forceRollout: # Rollout without requiring a version change - # Tears down the prior version and restarts the current Materialize instance - rolloutStrategy: ImmediatelyPromoteCausingDowntime ``` For more information on rollout configuration, view our [installation overview](/installation/#rollout-configuration).