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

Show file tree
Hide file tree
Changes from all commits
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
32 changes: 26 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 @@ -20,20 +20,24 @@ used:

{{% yaml-table data="self_managed/authentication_setting" %}}

{{< include-md file="shared-content/auth-kind-warning.md" >}}



## Configuring password authentication

{{< public-preview >}}This feature{{</ public-preview >}}

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. For all Materialize CR settings, see [here](/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
Expand Down Expand Up @@ -92,14 +96,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. For all Materialize CR settings, see [here](/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
Expand Down Expand Up @@ -148,6 +152,22 @@ 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?

Copy link
Contributor Author

@SangJunBak SangJunBak Dec 1, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

So I decided to use this strategy since with a 0dt upgrade, we'd also check the "up-to-datedness" of clusters and it'd force rehydration given it's spinning up new pods. Seems a bit excessive for what we're trying to do. I wonder if we should append a comment saying something like "to do this without downtime, use the 0dt rollout strategy"?

Copy link
Contributor

@def- def- Dec 1, 2025

Choose a reason for hiding this comment

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

CC @alex-hunt-materialize

Copy link
Contributor

@jubrad jubrad Dec 1, 2025

Choose a reason for hiding this comment

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

Yeah, we shouldn't use ImmediatelyPromoteCausingDowntime because of the explicitly stated downtime it'll create.

It's definitely possible that we want a rollout strategy that allows config refresh and envd restart, but we don't have it. I think we should stick with the standard wait until ready.

Copy link
Contributor Author

@SangJunBak SangJunBak Dec 1, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

Taking a step back and thinking of the user flow though, wouldn't there be downtime regardless since the user still needs to set up the passwords for auth?

Thinking of two scenarios:

1. User is in development mode (Feels like most common)
User doesn't care about creating downtime and just wants to setup auth asap

2. User already has a prod environment and wants to enable there
Between the time between a rollout and the user setting up the DDL for the necessary privileges/users/passwords, there's gonna be some downtime since all connections are gonna be invalidated

Copy link
Contributor Author

@SangJunBak SangJunBak Dec 1, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

It's definitely possible that we want a rollout strategy that allows config refresh and envd restart, but we don't have it.

Isn't this just specifying forceRollout? I'm pretty sure doing so just causes envd to restart and doesn't cause the cluster pods to go down

```

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

{{< include-md file="shared-content/auth-kind-warning.md" >}}

## Enabling RBAC

{{< include-md file="shared-content/enable-rbac.md" >}}
Expand Down
3 changes: 3 additions & 0 deletions doc/user/shared-content/auth-kind-warning.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 >}}