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

- 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.

<!--
Describe the contents of the PR briefly but completely.

If you write detailed commit messages, it is acceptable to copy/paste
them
here, or write "see commit messages for details." If there is only one
commit
in the PR, GitHub will have already added its commit message above.
-->

### Motivation

<!--
Which of the following best describes the motivation behind this PR?

  * This PR fixes a recognized bug.

    [Ensure issue is linked somewhere.]

  * This PR adds a known-desirable feature.

    [Ensure issue is linked somewhere.]

  * This PR fixes a previously unreported bug.

    [Describe the bug in detail, as if you were filing a bug report.]

  * This PR adds a feature that has not yet been specified.

[Write a brief specification for the feature, including justification
for its inclusion in Materialize, as if you were writing the original
     feature specification.]

   * This PR refactors existing code.

[Describe what was wrong with the existing code, if it is not obvious.]
-->

### Tips for reviewer

<!--
Leave some tips for your reviewer, like:

    * The diff is much smaller if viewed with whitespace hidden.
    * [Some function/module/file] deserves extra attention.
* [Some function/module/file] is pure code movement and only needs a
skim.

Delete this section if no tips.
-->

### Checklist

- [ ] This PR has adequate test coverage / QA involvement has been duly
considered. ([trigger-ci for additional test/nightly
runs](https://trigger-ci.dev.materialize.com/))
- [ ] This PR has an associated up-to-date [design
doc](https://github.com/MaterializeInc/materialize/blob/main/doc/developer/design/README.md),
is a design doc
([template](https://github.com/MaterializeInc/materialize/blob/main/doc/developer/design/00000000_template.md)),
or is sufficiently small to not require a design.
  <!-- Reference the design in the description. -->
- [ ] If this PR evolves [an existing `$T ⇔ Proto$T`
mapping](https://github.com/MaterializeInc/materialize/blob/main/doc/developer/command-and-response-binary-encoding.md)
(possibly in a backwards-incompatible way), then it is tagged with a
`T-proto` label.
- [ ] If this PR will require changes to cloud orchestration or tests,
there is a companion cloud PR to account for those changes that is
tagged with the release-blocker label
([example](MaterializeInc/cloud#5021)).
<!-- Ask in #team-cloud on Slack if you need help preparing the cloud
PR. -->
- [ ] If this PR includes major [user-facing behavior
changes](https://github.com/MaterializeInc/materialize/blob/main/doc/developer/guide-changes.md#what-changes-require-a-release-note),
I have pinged the relevant PM to schedule a changelog post.

Author: SangJunBak

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

@@ -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
@@ -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
@@ -148,6 +152,20 @@ 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
+```
+
+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" >}}

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 >}}