Skip to content

docs: Add rollout guidance for Self-Managed auth #34202

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
+29 −6
Open

docs: Add rollout guidance for Self-Managed auth #34202

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
daae2e9
docs: Add rollout guidance for Self-Managed auth
SangJunBak Nov 18, 2025
586e9cd
docs: Address review comments
SangJunBak Nov 19, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 25 additions & 6 deletions doc/user/content/security/self-managed/authentication.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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/):
Copy link
Contributor

@kay-kim kay-kim Nov 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So ... let's remove the link here ... because that page just gives all the fields ... and we're giving the specific fields here.

We could go "For all Materialize CR settings, see ... "


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
Expand Down Expand Up @@ -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/):
Copy link
Contributor

@kay-kim kay-kim Nov 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ditto.


| 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
Expand Down Expand Up @@ -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: <SOME_NEW_UUID> # Generate new UUID for rollout
forceRollout: <SOME_NEW_UUID> # Rollout without requiring a version change
# Tears down the prior version and restarts the current Materialize instance
rolloutStrategy: ImmediatelyPromoteCausingDowntime
Copy link
Contributor

@kay-kim kay-kim Nov 19, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jubrad and @sidsaw-mz ... any concerns about using the ImmediatelyPromoteCausingDowntime strategy here?

```

For more information on rollout configuration, view our [installation overview](/installation/#rollout-configuration).

{{< warning >}}
Copy link
Contributor

@kay-kim kay-kim Nov 18, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could we repeat this warning in both places above where we talk about setting authenticatorKind?

It's important enough that I think repeating in throughout (as people hop onto just their interested section)

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" >}}
Expand Down