[helm] Document and validate Secret-backed readiness probe auth

helm/templates/_secrets.tpl

@@ -131,6 +131,13 @@ Usage:
 {{- $errMessages = append $errMessages "secrets.env entries require 'name', 'secretName' and 'key'." -}}
 {{- end -}}
 {{- end -}}
+{{- if .Values.tablet.readinessProbe.healthCheckAuth -}}
+{{- range .Values.secrets.env -}}
+{{- if eq .name "READINESS_HEALTH_CHECK_AUTH" -}}
+{{- $errMessages = append $errMessages "tablet.readinessProbe.healthCheckAuth conflicts with the secrets.env entry named READINESS_HEALTH_CHECK_AUTH; set only one." -}}
+{{- end -}}
+{{- end -}}
+{{- end -}}
 {{- $errMessages = without $errMessages "" -}}
 {{- join "\n" $errMessages -}}
 {{- end -}}

helm/tests/secrets_test.yaml

@@ -145,3 +145,26 @@ tests:
           path: data["server.yaml"]
           pattern: 'config\.providers: directory,env'
         template: templates/configmap.yaml
+
+  - it: sources the readiness probe credential from a Secret
+    set:
+      secrets.env:
+        - name: READINESS_HEALTH_CHECK_AUTH
+          secretName: fluss-readiness-probe-auth
+          key: auth
+    asserts:
+      - contains:
+          path: spec.template.spec.containers[0].env
+          content:
+            name: READINESS_HEALTH_CHECK_AUTH
+            valueFrom:
+              secretKeyRef:
+                name: fluss-readiness-probe-auth
+                key: auth
+        template: templates/sts-tablet.yaml
+      # The probe command must not export the variable, otherwise it would
+      # override the Secret-sourced value inherited from the container.
+      - notMatchRegex:
+          path: spec.template.spec.containers[0].readinessProbe.exec.command[2]
+          pattern: 'export READINESS_HEALTH_CHECK_AUTH'
+        template: templates/sts-tablet.yaml

helm/tests/secrets_validate_test.yaml

@@ -57,3 +57,14 @@ tests:
     asserts:
       - failedTemplate:
           errorMessage: "VALUES VALIDATION:\nsecrets.env entries require 'name', 'secretName' and 'key'."
+
+  - it: fails when the probe credential is set both inline and via secrets.env
+    set:
+      tablet.readinessProbe.healthCheckAuth: "client.security.protocol:SASL"
+      secrets.env:
+        - name: READINESS_HEALTH_CHECK_AUTH
+          secretName: fluss-readiness-probe-auth
+          key: auth
+    asserts:
+      - failedTemplate:
+          errorMessage: "VALUES VALIDATION:\ntablet.readinessProbe.healthCheckAuth conflicts with the secrets.env entry named READINESS_HEALTH_CHECK_AUTH; set only one."

helm/values.yaml

@@ -79,6 +79,22 @@ tablet:
     # or escaping needed). Required only when the local client listener
     # enforces SASL. Example:
     #   healthCheckAuth: "client.security.protocol:SASL;client.sasl.mechanism:PLAIN;client.security.sasl.username:admin;client.security.sasl.password:admin-pass"
+    #
+    # This value is inlined into the StatefulSet's probe command, so it is
+    # readable by anyone who can read the rendered manifest. To keep the
+    # credential in a Secret instead, leave this empty and declare the
+    # environment variable the probe reads under `secrets.env`:
+    #   secrets:
+    #     env:
+    #       - name: READINESS_HEALTH_CHECK_AUTH
+    #         secretName: fluss-readiness-probe-auth
+    #         key: auth
+    # The exec probe inherits the container environment, so readiness-check.sh
+    # picks the value up unchanged.
+    #
+    # When the authorizer is enabled, the principal in this credential needs
+    # DESCRIBE on the cluster resource, otherwise the health call is denied and
+    # the pod never becomes Ready.
     healthCheckAuth: ""
   extraVolumes: []
   extraVolumeMounts: []

website/docs/install-deploy/deploying-with-helm.md

@@ -873,6 +873,38 @@ tablet:
 | `failureThreshold` | `200`   | Max consecutive probe failures before marking the pod as unready. With `periodSeconds=5`, this allows up to ~16 minutes for recovery.          |
 | `periodSeconds`    | `5`     | How often the probe runs.                                                                                                                      |
 
+##### Probe credentials on a SASL cluster
+
+The probe connects to the pod's own client listener as a regular Fluss client. When that
+listener enforces SASL, the probe needs credentials or no TabletServer ever becomes Ready.
+With the authorizer enabled, the principal also needs `DESCRIBE` on the cluster resource.
+
+The credential is a single-line string of semicolon-separated `key:value` pairs. Supply it in
+one of two ways.
+
+Inline, which is simplest but puts the credential in plain text in the rendered StatefulSet:
+
+```yaml
+tablet:
+  readinessProbe:
+    healthCheckAuth: "client.security.protocol:SASL;client.security.sasl.mechanism:PLAIN;client.security.sasl.username:probe;client.security.sasl.password:probe-pass"
+```
+
+Or from a Secret, which keeps it out of the manifest. Leave `healthCheckAuth` empty and
+declare the environment variable the probe reads:
+
+```yaml
+secrets:
+  env:
+    - name: READINESS_HEALTH_CHECK_AUTH
+      secretName: fluss-readiness-probe-auth
+      key: auth
+```
+
+The exec probe inherits the container environment, so the value reaches the check unchanged.
+Setting both forms fails the render, because the inline form would silently override the
+Secret.
+
 :::note
 The CoordinatorServer does not need the Cluster Health API probe — it does not host data replicas, so a simple TCP check is sufficient.
 The Coordinator should be upgraded **after** all TabletServers are fully upgraded and recovered.