Fluss Documentation add CoordinatorServer High Availability (HA) Setup

website/docs/install-deploy/deploying-distributed-cluster.md

@@ -151,6 +151,65 @@ On **Node1**, **Node2** and **Node3**, start a TabletServer as follows.
 
 After that, you have successfully deployed a distributed Fluss cluster.
 
+## Fluss CoordinatorServer High Availability (HA) Setup
+
+By default, the distributed cluster example above deploys a single CoordinatorServer on Node0,
+which is a single point of failure for admin operations (e.g., creating databases/tables).
+Fluss supports built-in high availability (HA) for the CoordinatorServer based on ZooKeeper
+leader election, requiring no additional configuration options.
+
+### How it works
+
+When multiple CoordinatorServer instances point to the same ZooKeeper cluster, they participate
+in leader election. Exactly one is elected as the **leader** and serves the full coordinator
+services; the others run as **standby**. If the leader fails, a standby is promoted and
+increments the coordinator epoch to fence off the old leader.
+
+:::note
+During failover, admin operations (e.g., creating/dropping tables) are temporarily unavailable,
+but data reads and writes on existing tables are **not** affected. The time to elect a new
+leader is bounded by `zookeeper.client.session-timeout` (default 60 seconds).
+:::
+
+### Configuring CoordinatorServer HA
+
+To enable HA, start at least two CoordinatorServer instances on different nodes, all configured
+with the same `zookeeper.address` and `zookeeper.path.root`. No extra configuration options are
+needed beyond what a distributed deployment already requires.
+
+Extending the four-node example above, add a second CoordinatorServer on a new node:
+
+**Node4**
+
+```yaml title="server.yaml"
+# coordinator server
+bind.listeners: FLUSS://192.168.10.104:9123
+
+zookeeper.address: 192.168.10.199:2181
+zookeeper.path.root: /fluss
+
+# When running in distributed mode, be sure to point to a remote path—
+# e.g. oss://bucket/path for OSS or hdfs://namenode:port/path for HDFS.
+# Otherwise, queries will fail with a “No such file or directory” error.
+remote.data.dir: hdfs://namenode:port/tmp/fluss-remote-data
+```
+
+### Starting CoordinatorServer HA
+
+To deploy a Fluss cluster with CoordinatorServer HA, you should first start a CoordinatorServer instance on **Node0**.
+Then, start the second CoordinatorServer instance on **Node4**.
+
+**CoordinatorServer**
+
+On **Node0** and **Node4**, start a CoordinatorServer as follows.
+
+```shell
+./bin/coordinator-server.sh start
+```
+
+After that, you have successfully deployed a distributed Fluss cluster with CoordinatorServer HA.
+
+
 ## Interacting with Fluss
 
 After the Fluss cluster is started, you can use **Fluss Client** (e.g., Flink SQL Client) to interact with Fluss.
@@ -169,13 +228,26 @@ You can start a Flink standalone cluster refer to [Flink Environment Preparation
 #### Add catalog
 
 In Flink SQL client, a catalog is created and named by executing the following query:
+
+- Single CoordinatorServer:
+
 ```sql title="Flink SQL"
 CREATE CATALOG fluss_catalog WITH (
   'type' = 'fluss',
   'bootstrap.servers' = '192.168.10.100:9123'
 );
 ```
 
+- CoordinatorServer HA:
+
+```sql title="Flink SQL"
+CREATE CATALOG fluss_catalog WITH (
+  'type' = 'fluss',
+  'bootstrap.servers' = '192.168.10.100:9123,192.168.10.104:9123'
+);
+```
+
+
 #### Do more with Fluss
 
 After the catalog is created, you can use Flink SQL Client to do more with Fluss, for example, create a table, insert data, query data, etc.

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

@@ -55,7 +55,14 @@ docker run \
 
 ### Start Fluss CoordinatorServer
 
-Start Fluss CoordinatorServer in daemon and connect to Zookeeper.
+You can start one or more coordinator servers based on your needs. For a production environment,
+ensure that you have multiple coordinator servers for high availability (HA).
+
+#### Start with One CoordinatorServer
+
+If you just want to start a sample test, you can start only one CoordinatorServer in daemon and connect to Zookeeper.
+The command is as follows:
+
 ```bash
 docker run \
     --name coordinator-server \
@@ -69,6 +76,30 @@ internal.listener.name: INTERNAL
     -d apache/fluss:$FLUSS_DOCKER_VERSION$ coordinatorServer
 ```
 
+#### Start with CoordinatorServer HA
+
+To enable CoordinatorServer HA, start a second CoordinatorServer in daemon and connect to the same Zookeeper.
+The CoordinatorServers participate in leader election via Zookeeper: exactly one is elected as the leader,
+and the other runs as standby. The command is as follows:
+
+```bash
+docker run \
+    --name coordinator-server-1 \
+    --network=fluss-demo \
+    --env FLUSS_PROPERTIES="zookeeper.address: zookeeper:2181
+bind.listeners: INTERNAL://coordinator-server-1:0, CLIENT://coordinator-server-1:9123
+advertised.listeners: CLIENT://localhost:9127
+internal.listener.name: INTERNAL
+" \
+    -p 9127:9123 \
+    -d apache/fluss:$FLUSS_DOCKER_VERSION$ coordinatorServer
+```
+
+When CoordinatorServer HA is enabled, list the addresses of all CoordinatorServer instances in `bootstrap.servers`
+so that clients can connect to a surviving coordinator even if one goes down, e.g.,
+`'bootstrap.servers' = 'localhost:9123,localhost:9127'`.
+
+
 ### Start Fluss TabletServer
 
 You can start one or more tablet servers based on your needs. For a production environment,
@@ -221,9 +252,9 @@ volumes:
       device: "tmpfs"
 ```
 
-#### Compose file to start Fluss cluster with multi TabletServer
+#### Compose file to start Fluss cluster with multi CoordinatorServer and TabletServer
 
-You can use the following `docker-compose.yml` file to start a Fluss cluster with one `CoordinatorServer` and three `TabletServers`.
+You can use the following `docker-compose.yml` file to start a Fluss cluster with two `CoordinatorServers` (HA) and three `TabletServers`.
 
 ```yaml
 services:
@@ -242,6 +273,21 @@ services:
         remote.data.dir: /tmp/fluss/remote-data
     ports:
       - "9123:9123"
+  coordinator-server-1:
+    image: apache/fluss:$FLUSS_DOCKER_VERSION$
+    command: coordinatorServer
+    depends_on:
+      - zookeeper
+    environment:
+      - |
+        FLUSS_PROPERTIES=
+        zookeeper.address: zookeeper:2181
+        bind.listeners: INTERNAL://coordinator-server-1:0, CLIENT://coordinator-server-1:9123
+        advertised.listeners: CLIENT://localhost:9127
+        internal.listener.name: INTERNAL
+        remote.data.dir: /tmp/fluss/remote-data
+    ports:
+      - "9127:9123"
   tablet-server-0:
     image: apache/fluss:$FLUSS_DOCKER_VERSION$
     command: tabletServer
@@ -349,13 +395,26 @@ bin/sql-client.sh
 ### Create Fluss Catalog
 
 Use the following SQL to create a Fluss catalog:
+
+- Single CoordinatorServer:
+
 ```sql title="Flink SQL"
 CREATE CATALOG fluss_catalog WITH (
     'type' = 'fluss',
     'bootstrap.servers' = 'localhost:9123'
 );
 ```
 
+- CoordinatorServer HA:
+
+```sql title="Flink SQL"
+CREATE CATALOG fluss_catalog WITH (
+  'type' = 'fluss',
+  'bootstrap.servers' = 'localhost:9123,localhost:9127'
+);
+```
+
+
 ```sql title="Flink SQL"
 USE CATALOG fluss_catalog;
 ```