diff --git a/website/docs/install-deploy/deploying-distributed-cluster.md b/website/docs/install-deploy/deploying-distributed-cluster.md index edb89cf7409..4671032405e 100644 --- a/website/docs/install-deploy/deploying-distributed-cluster.md +++ b/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,6 +228,9 @@ 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', @@ -176,6 +238,16 @@ CREATE CATALOG fluss_catalog WITH ( ); ``` +- 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. diff --git a/website/docs/install-deploy/deploying-with-docker.md b/website/docs/install-deploy/deploying-with-docker.md index 6d7709950b8..26adee9eae1 100644 --- a/website/docs/install-deploy/deploying-with-docker.md +++ b/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,6 +395,9 @@ 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', @@ -356,6 +405,16 @@ CREATE CATALOG fluss_catalog WITH ( ); ``` +- 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; ```