edu-8: tweak self-managed installs for resource delays + security men…

doc/user/content/headless/self-managed-deployments/enabled-auth-setting-warning.md

@@ -0,0 +1,6 @@
+---
+headless: true
+---
+{{< warning >}}
+Once enabled, 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 >}}

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

@@ -20,26 +20,37 @@ used:
 
 {{% yaml-table data="self_managed/authentication_setting" %}}
 
-{{< include-md file="shared-content/auth-kind-warning.md" >}}
+{{% include-headless
+"/headless/self-managed-deployments/enabled-auth-setting-warning" %}}
 
+### Configuring SASL/SCRAM authentication
 
+{{< note>}}
+SASL/SCRAM-SHA-256 authentication requires Materialize `v26.0.0` or later.
+{{< /note >}}
 
-## Configuring password authentication
+SASL authentication requires users to log in with a password.
 
-{{< public-preview >}}This feature{{</ public-preview >}}
+When SASL authentication is enabled:
+- **PostgreSQL connections** (e.g., `psql`, client libraries, [connection
+  poolers](/integrations/connection-pooling/)) use SCRAM-SHA-256 authentication.
+- **HTTP/Web Console connections** use standard password authentication.
 
-Password authentication requires users to log in with a password.
+This hybrid approach provides maximum security for SQL connections while
+maintaining compatibility with web-based tools.
 
-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/).
+To configure Self-Managed Materialize for SASL/SCRAM authentication, update the
+following fields:
 
- Configuration | Description
----------------| ------------
-`spec.authenticatorKind` | Set to `Password` to enable password authentication.
-`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.
+| Resource | Configuration | Description
+|----------|---------------| ------------
+| Materialize CR | `spec.authenticatorKind` | Set to `Sasl` to enable SASL/SCRAM-SHA-256 authentication for PostgreSQL connections.
+| Kubernetes Secret | `external_login_password_mz_system` | Specify the password for the `mz_system` user, who is the only user initially available. Add `external_login_password_mz_system` to the Kubernetes Secret referenced in the Materialize CR's `spec.backendSecretName` field.
 
-An example Materialize CR YAML file:
+The following example Kubernetes manifest includes configuration for
+SASL/SCRAM-SHA-256 authentication:
 
-```hc {hl_lines="14 24"}
+```hc {hl_lines="15 25"}
 apiVersion: v1
 kind: Namespace
 metadata:
@@ -53,6 +64,7 @@ metadata:
 stringData:
   metadata_backend_url: "..."
   persist_backend_url: "..."
+  license_key: "..."
   external_login_password_mz_system: "enter_mz_system_password"
 ---
 apiVersion: materialize.cloud/v1alpha1
@@ -61,51 +73,31 @@ metadata:
   name: 12345678-1234-1234-1234-123456789012
   namespace: materialize-environment
 spec:
-  environmentdImageRef: materialize/environmentd:v0.147.2
+  environmentdImageRef: materialize/environmentd:v26.12.1
   backendSecretName: materialize-backend
-  authenticatorKind: Password
+  authenticatorKind: Sasl
 ```
 
-#### Logging in and creating users
-
-Initially, only the `mz_system` user [^1] is available. To create additional
-users:
-
-1. Login as the `mz_system` user, using the
-`external_login_password_mz_system` password,
-![Image of Materialize Console login screen with mz_system user](/images/mz_system_login.png
-"Materialize Console login screen with mz_system user")
-
-1. Use [`CREATE ROLE ... WITH LOGIN PASSWORD ...`](/sql/create-role) to create
-   new users:
-
-   ```mzsql
-   CREATE ROLE <user> WITH LOGIN PASSWORD '<password>';
-   ```
+{{% include-headless
+"/headless/self-managed-deployments/enabled-auth-setting-warning" %}}
 
-[^1]: The `mz_system` user is also used by the Materialize Operator for upgrades
-and maintenance tasks.
+### Configuring password authentication
 
-## Configuring SASL/SCRAM authentication
+{{< public-preview />}}
 
-{{< note >}}
-SASL/SCRAM-SHA-256 authentication requires Materialize `v26.0.0` or later.
-{{</ note >}}
-
-SASL/SCRAM-SHA-256 authentication is a challenge-response authentication mechanism
-that provides security for **PostgreSQL wire protocol connections**. It is
-compatible with PostgreSQL clients that support SCRAM-SHA-256.
+Password authentication requires users to log in with a password.
 
-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/).
+To configure Self-Managed Materialize for password authentication, update the following fields:
 
-| Configuration | Description
-|---------------| ------------
-|`spec.authenticatorKind` | Set to `Sasl` to enable SASL/SCRAM-SHA-256 authentication for PostgreSQL connections.
-|`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.
+| Resource | Configuration | Description
+|----------|---------------| ------------
+| Materialize CR | `spec.authenticatorKind` | Set to `Password` to enable password authentication.
+| Kubernetes Secret | `external_login_password_mz_system` | Specify the password for the `mz_system` user, who is the only user initially available. Add `external_login_password_mz_system` to the Kubernetes Secret referenced in the Materialize CR's `spec.backendSecretName` field.
 
-An example Materialize CR YAML file:
+The following example Kubernetes manifest includes configuration for password
+authentication:
 
-```hc {hl_lines="14 24"}
+```hc {hl_lines="15 25"}
 apiVersion: v1
 kind: Namespace
 metadata:
@@ -119,6 +111,7 @@ metadata:
 stringData:
   metadata_backend_url: "..."
   persist_backend_url: "..."
+  license_key: "..."
   external_login_password_mz_system: "enter_mz_system_password"
 ---
 apiVersion: materialize.cloud/v1alpha1
@@ -127,47 +120,51 @@ metadata:
   name: 12345678-1234-1234-1234-123456789012
   namespace: materialize-environment
 spec:
-  environmentdImageRef: materialize/environmentd:v0.147.2
+  environmentdImageRef: materialize/environmentd:v26.12.1
   backendSecretName: materialize-backend
-  authenticatorKind: Sasl
+  authenticatorKind: Password
 ```
 
-### Logging in and creating users
+{{% include-headless
+"/headless/self-managed-deployments/enabled-auth-setting-warning" %}}
 
-The process is the same as for [password authentication](#logging-in-and-creating-users):
+## Logging in and creating users
 
-1. Login as the `mz_system` user using the `external_login_password_mz_system` password
-2. Use [`CREATE ROLE ... WITH LOGIN PASSWORD ...`](/sql/create-role) to create new users
+When authentication is enabled, only the `mz_system` user is initially
+available. To create additional users:
 
-User passwords are automatically stored in SCRAM-SHA-256 format in the database.
+1. Login as the `mz_system` user, using the `external_login_password_mz_system`
+password. ![Image of Materialize Console login screen with mz_system
+user](/images/mz_system_login.png "Materialize Console login screen with
+mz_system user")
 
-### Authentication behavior
+1. Use [`CREATE ROLE ... WITH LOGIN PASSWORD ...`](/sql/create-role) to create
+new users:
 
-When SASL authentication is enabled:
+   ```mzsql
+   CREATE ROLE <user> WITH LOGIN PASSWORD '<password>';
+   ```
 
-- **PostgreSQL connections** (e.g., `psql`, client libraries, [connection
-  poolers](/integrations/connection-pooling/)) use SCRAM-SHA-256 authentication
-- **HTTP/Web Console connections** use standard password authentication
+1. Log out as `mz_system` user.
 
-This hybrid approach provides maximum security for SQL connections while maintaining
-compatibility with web-based tools.
+   {{< important >}}
 
-## Deploying authentication
+   In general, other than the initial login to create new users, avoid using
+   `mz_system` since `mz_system` also used by the Materialize Operator for
+   upgrades and maintenance tasks. {{< /important >}}
 
-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
-```
+1. Login as one of the created users.
 
-For more information on rollout configuration, view our [upgrade overview](/self-managed-deployments/upgrading/#rollout-configuration).
+## RBAC
 
-{{< include-md file="shared-content/auth-kind-warning.md" >}}
+For details on role-based access control (RBAC), including enabling RBAC, see
+[Access Control](/security/self-managed/access-control/).
 
-## Enabling RBAC
+{{< warning >}}
+If RBAC is not enabled, all users have <red>**superuser**</red> privileges.
+{{< /warning >}}
 
-{{< include-md file="shared-content/enable-rbac.md" >}}
+## See also
 
-See [Access Control](/security/self-managed/access-control/) for details on role based authorization.
+- For all Materialize CR settings, see [Materialize CRD Field
+Descriptions](/installation/appendix-materialize-crd-field-descriptions/).

doc/user/content/self-managed-deployments/installation/install-on-aws.md

@@ -120,6 +120,17 @@ An active AWS account with appropriate permissions to create:
 
 {{< /warning >}}
 
+{{< tip >}}
+
+The simple example used in this tutorial enables [Password
+authentication](https://github.com/MaterializeInc/materialize-terraform-self-managed/blob/main/aws/examples/simple/main.tf#L380)
+for the Materialize instance. To use a different authentication method, update
+[`authenticator_kind`](https://github.com/MaterializeInc/materialize-terraform-self-managed/blob/main/kubernetes/modules/materialize-instance/README.md#input_authenticator_kind).
+See [Authentication](/security/self-managed/authentication/) for the supported
+authentication mechanisms.
+
+{{< /tip >}}
+
 ### Step 1: Set Up the Environment
 
 1. Open a terminal window.
@@ -331,18 +342,19 @@ guide](/self-managed-deployments/deployment-guidelines/aws-deployment-guidelines
 
 See also:
 
+- [Configuring System
+  Parameters](/self-managed-deployments/configuration-system-parameters/)
 - [Materialize Operator
   Configuration](/self-managed-deployments/operator-configuration/)
 - [Materialize CRD Field
   Descriptions](/self-managed-deployments/materialize-crd-field-descriptions/)
 
-
 ## Cleanup
 
 {{% self-managed/cleanup-cloud %}}
 
 
 ## See Also
 
-
 - [Troubleshooting](/self-managed-deployments/troubleshooting/)
+- [Security](/security/self-managed/)

doc/user/content/self-managed-deployments/installation/install-on-azure.md

@@ -118,6 +118,16 @@ An active Azure subscription with appropriate permissions to create:
 
 {{< /warning >}}
 
+
+{{< tip >}}
+
+The simple example used in this tutorial enables [Password
+authentication](https://github.com/MaterializeInc/materialize-terraform-self-managed/blob/main/azure/examples/simple/main.tf#L340)
+for the Materialize instance. To use a different authentication method, update
+[`authenticator_kind`](https://github.com/MaterializeInc/materialize-terraform-self-managed/blob/main/kubernetes/modules/materialize-instance/README.md#input_authenticator_kind).
+See [Authentication](/security/self-managed/authentication/) for the supported
+authentication mechanisms. {{< /tip >}}
+
 ### Step 1: Set Up the Environment
 
 1. Open a terminal window.
@@ -346,6 +356,8 @@ Autoscaling: Uses Azure's native cluster autoscaler that integrates directly wit
 {{< /note >}}
 
 See also:
+- [Configuring System
+  Parameters](/self-managed-deployments/configuration-system-parameters/)
 - [Materialize Operator
   Configuration](/self-managed-deployments/operator-configuration/)
 - [Materialize CRD Field
@@ -357,5 +369,5 @@ See also:
 
 ## See Also
 
-- [Materialize Operator Configuration](/installation/configuration/)
-- [Troubleshooting](/installation/troubleshooting/)
+- [Troubleshooting](/self-managed-deployments/troubleshooting/)
+- [Security](/security/self-managed/)

doc/user/content/self-managed-deployments/installation/install-on-gcp.md

@@ -116,6 +116,15 @@ A Google account with permission to:
 
 {{< /warning >}}
 
+{{< tip >}}
+
+The simple example used in this tutorial enables [Password
+authentication](https://github.com/MaterializeInc/materialize-terraform-self-managed/blob/main/gcp/examples/simple/main.tf#L332)
+for the Materialize instance. To use a different authentication method, update
+[`authenticator_kind`](https://github.com/MaterializeInc/materialize-terraform-self-managed/blob/main/kubernetes/modules/materialize-instance/README.md#input_authenticator_kind).
+See [Authentication](/security/self-managed/authentication/) for the supported
+authentication mechanisms. s {{< /tip >}}
+
 ### Step 1: Set Up the Environment
 
 1. Open a terminal window.
@@ -360,6 +369,8 @@ guide](/self-managed-deployments/deployment-guidelines/gcp-deployment-guidelines
 {{< /note >}}
 
 See also:
+- [Configuring System
+  Parameters](/self-managed-deployments/configuration-system-parameters/)
 - [Materialize Operator
   Configuration](/self-managed-deployments/operator-configuration/)
 - [Materialize CRD Field
@@ -371,5 +382,5 @@ See also:
 
 ## See Also
 
-- [Materialize Operator Configuration](/installation/configuration/)
-- [Troubleshooting](/installation/troubleshooting/)
+- [Troubleshooting](/self-managed-deployments/troubleshooting/)
+- [Security](/security/self-managed/)

doc/user/content/self-managed-deployments/installation/install-on-local-kind.md

@@ -130,12 +130,13 @@ Starting in v26.0, Self-Managed Materialize requires a license key.
    name: materialize-backend
    namespace: materialize-environment
    stringData:
-   metadata_backend_url: "postgres://materialize_user:materialize_pass@postgres.materialize.svc.cluster.local:5432/materialize_db?sslmode=disable"
-   persist_backend_url: "s3://minio:minio123@bucket/12345678-1234-1234-1234-123456789012?endpoint=http%3A%2F%2Fminio.materialize.svc.cluster.local%3A9000&region=minio"
-   license_key: "<enter your license key here>"
+     metadata_backend_url: "postgres://materialize_user:materialize_pass@postgres.materialize.svc.cluster.local:5432/materialize_db?sslmode=disable"
+     persist_backend_url: "s3://minio:minio123@bucket/12345678-1234-1234-1234-123456789012?endpoint=http%3A%2F%2Fminio.materialize.svc.cluster.local%3A9000&region=minio"
+     license_key: "<enter your license key here>"
    ---
    ```
 
+
 1. Install the Materialize Helm chart.
 
    1. Add the Materialize Helm chart repository.
@@ -272,6 +273,12 @@ Starting in v26.0, Self-Managed Materialize requires a license key.
 
     1. Verify the installation and check the status:
 
+       {{< note >}}
+       It may take approximately 1-2 minutes for all resources to appear in the
+       namespace. Allow up to 90 seconds before verifying resource creation with
+       `kubectl get` commands.
+       {{< /note >}}
+
        ```shell
        kubectl get all -n materialize-environment
        ```
@@ -323,10 +330,14 @@ Starting in v26.0, Self-Managed Materialize requires a license key.
 
       {{< /tip >}}
 
+
 ## Next steps
 
 {{% self-managed/next-steps %}}
 
+- To enable authentication and authorization, see
+  [Security](/security/self-managed/).
+
 ## Clean up
 
 To delete the whole local deployment (including Materialize instances and data):