Securing Fluss

Applies toSelf-Managed v3

5 min read

On this page

This document explains how to configure and troubleshoot SASL/PLAIN authentication across the client, internal, and ZooKeeper communication planes of a Fluss cluster. It details how to secure cluster metadata, manage client credentials, and resolve common deployment validation and connection errors.

Overview

The Ververica distribution of Fluss currently supports a single built-in security mechanism: SASL/PLAIN authentication. SASL can be enabled independently on three planes:

Plane	Listener / Channel	What it protects
Plane	Listener / Channel	What it protects
Client-facing	CLIENT listener (port 9124 by default)	External applications, Flink jobs, the Java SDK, anything outside the Fluss cluster
Internal	INTERNAL listener (port 9123 by default)	Coordinator ↔ tablet server traffic
ZooKeeper	ZK Ensemble	Fluss-to-ZooKeeper traffic; protects cluster metadata

The three planes are configured independently and can be enabled in any combination.

For other security topics (transport encryption, authorization, other authentication mechanisms), see Other Mechanisms.

For the upstream conceptual reference, see the Fluss security overview and Fluss authentication documentation.

Prerequisites

A running Fluss cluster deployed via the fluss-bundle chart. See Deploying Fluss on Kubernetes.
kubectl access to the namespace hosting Fluss.
A way to inject sensitive values into the Helm release at deploy time. See Where credentials come from.

SASL Authentication

Where credentials come from

For production deployments, source your SASL credentials from a pre-existing Kubernetes Secret instead of inlining them in your values.yaml file. You can find documentation for this mechanism (existingSecret.name, usernameKey, and passwordKey) in the upstream Fluss Helm chart guide.

The plane-specific examples below show inline credentials as <PLACEHOLDER> for brevity. You must switch to the existingSecret form in production environments.

Configuring Client-Facing SASL

Client-facing SASL forces external clients to authenticate before they can interact with the CLIENT listener. This setting does not affect internal coordinator and tablet traffic.

Set the mechanism to plain and list the allowed users under fluss.security.client.sasl.plain.users. Each entry is a username and password pair, and you can list as many users as you need:

YAML

1fluss:
2  security:
3    client:
4      sasl:
5        mechanism: plain
6        plain:
7          users:
8            - username: <CLIENT_USERNAME>
9              password: <CLIENT_PASSWORD>
10            # repeat the pair for additional users

For the full set of configurable fields under fluss:, refer to the Fluss Helm Chart - Additional Notes.docx documentation.

For configuring Flink and Java SDK clients to present SASL credentials on connect, see Reading and Writing Fluss.

Verifying

Connect from a client without credentials. The connection must fail.

Connect with your configured username and password. The connection must succeed.

Configuring Internal (Coordinator ↔ Tablet) SASL

Internal SASL authenticates traffic on the INTERNAL listener, which is the channel that coordinator and tablet servers use to communicate with each other. This plane uses a single shared credential pair, so both servers act as the same SASL principal when they connect to peers.

YAML

1fluss:
2  security:
3    internal:
4      sasl:
5        mechanism: plain
6        plain:
7          username: <INTERNAL_USERNAME>
8          password: <INTERNAL_PASSWORD>

Important

If you leave the username and password empty under security.internal.sasl.plain while mechanism: plain is set, the chart auto-generates a deterministic credential pair derived from the Helm release name. This behavior is acceptable for ephemeral test clusters, but you must set explicit credentials in production so you can rotate and audit them. The chart emits a VALUES WARNING when you use the auto-generated default.

The internal listener is not reachable by external clients, so you do not need to perform any client-side configuration.

Verifying

Restart a tablet pod and confirm that it joins the cluster. The coordinator logs must show the tablet rejoining without authentication errors.

Configuring ZooKeeper SASL

Fluss stores cluster metadata in ZooKeeper. Enabling SASL on this channel ensures that only the Fluss servers, and not arbitrary clients on the network, can read or modify that metadata. This plane configures both the bundled ZooKeeper sub-chart on the server side and the Fluss servers on the client side.

Step 1 - Configure the bundled ZooKeeper

The fluss-bundle chart includes the Bitnami ZooKeeper chart as a dependency. Enable client authentication on the ZooKeeper chart and supply the same credentials that Fluss will use:

YAML

1zookeeper:
2  auth:
3    client:
4      enabled: true
5      clientUser: <ZK_USERNAME>
6      clientPassword: <ZK_PASSWORD>
7      serverUsers: <ZK_USERNAME>
8      serverPasswords: <ZK_PASSWORD>
9  extraEnvVars:
10    - name: JVMFLAGS
11      value: "-Dzookeeper.extendedTypesEnabled=true -Dzookeeper.enforce.auth.enabled=true -Dzookeeper.enforce.auth.schemes=sasl -Djute.maxbuffer=104857600"

The JVMFLAGS override turns on zookeeper.enforce.auth.enable=true so that ZooKeeper rejects any client that does not authenticate using SASL. Without this flag, ZooKeeper still accepts unauthenticated connections even when auth.client.enabled is true.

If you do not want to inline these credentials in your values.yaml file, refer to the upstream Bitnami ZooKeeper chart documentation for its secret-injection options.

Step 2 - Configure Fluss to authenticate to ZooKeeper

YAML

1fluss:
2  security:
3    zookeeper:
4      sasl:
5        mechanism: plain
6        plain:
7          username: <ZK_USERNAME>
8          password: <ZK_PASSWORD>

Verifying

Restart the Fluss coordinator and tablet pods. They should connect to ZooKeeper without KeeperException$NoAuthException or Will not attempt to authenticate using SASL warnings in the logs.

Rotating Credentials

To rotate any of the three credential pairs, update the corresponding values and run helm upgrade on the release. The chart re-renders the JAAS Secret and rolls the coordinator and tablet StatefulSets. You might experience brief unavailability during the rolling restart. For more information, see the upgrade-availability note in Deploying Fluss on Kubernetes.

For client-facing SASL specifically, allow both old and new credentials during the rollover through the following workflow:

By listing both username/password pairs under security.client.sasl.plain.users, upgrading once, switching clients to the new credentials, then removing the old user and upgrading again

Troubleshooting

Authentication failures on the client listener

Symptom: Clients log Authentication failed , SaslAuthenticationException or the connection drops immediately after the SASL handshake.

To resolve this issue, complete the following steps:

Confirm the client sets client.security.protocol=SASL and client.security.sasl.mechanism=PLAIN (see Reading and Writing Fluss).
Confirm that the username and password match an entry in security.client.sasl.plain.users.
Run helm upgrade after you update the credentials so that the chart renders the new JAAS Secret and rolls the pods.

Coordinator and tablet cannot communicate after enabling internal SASL

Symptom: the coordinator log shows tablet servers as offline; tablet logs show authentication errors when connecting to the coordinator's INTERNAL listener.

Both pods read the same JAAS Secret rendered by the chart, so a same-release configuration always agrees. If you see this error, you might be templating the coordinator and tablet from separate Helm releases, which is uncommon. You must use a single release.
If a pod's startup log preamble reports auto-generated credentials, the explicit security.internal.sasl.plain.{username,password} values were not set. Fill in these values and upgrade the release again.

Fluss cannot connect to ZooKeeper after enabling ZK SASL

Symptom: Fluss pods crash-loop with KeeperErrorCode = AuthFailed or log Will not attempt to authenticate using SASL.

To resolve this issue, check the following configurations:

The username and password under fluss.security.zookeeper.sasl.plain must match zookeeper.auth.client.clientUser and zookeeper.auth.client.clientPassword. You configure both halves separately, and they must agree.
The ZooKeeper pods must include - zookeeper.enforce.auth.enabled=true in the JVMFLAGS override. Without this flag, ZooKeeper accepts unauthenticated connections in some Bitnami image versions. This makes the SASL configuration appear to work, but ZooKeeper does not actually enforce it.
The chart only emits the ZooKeeper SASL stanza when you set security.zookeeper.sasl.mechanism. Verify that this value is present in your configuration.

VALUES VALIDATION errors at helm install / upgrade time

The chart validates the SASL configuration before rendering. Review the following common errors and their solutions:

The security.<plane>.sasl.mechanism must be empty or: plain or only plain (or empty / unset) is currently supported.
The security.client.sasl.plain.users must contain at least one user when security.client.sasl.mechanism is plain or add at least one username/password pair.
ssecurity.zookeeper.sasl.plain.{username,password,loginModuleClass} must not be empty when security.zookeeper.sasl.mechanism is plain — supply all three; loginModuleClass has a default but must remain non-empty.

Other Mechanisms

Fluss currently supports only SASL/PLAIN for authentication. The current distribution does not support the following features:

Other SASL mechanisms, such as SCRAM, GSSAPI and Kerberos, or OAUTHBEARER
Transport-layer encryption (TLS and mTLS) for the CLIENT or INTERNAL listeners
Pluggable authorization, such as ACLs or RBAC

Until support lands, secure the network path to your Fluss listeners using Kubernetes NetworkPolicies, namespace isolation, or a service mesh.