Skip to content

Commit ca19481

Browse files
swuferhongwuchong
swuferhong
authored and
wuchong
committed
[docs] Add docs for racks and upgrading (#1148)
(cherry picked from commit 6431dce)
1 parent 1af0124 commit ca19481

File tree

4 files changed

+163
-1
lines changed

4 files changed

+163
-1
lines changed

‎website/docs/engine-flink/getting-started.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -32,8 +32,9 @@ For a quick introduction to running Flink, refer to the [Quick Start](quickstart
3232

3333

3434
## Feature Support
35-
Fluss only supports Apache Flink's Table API.
35+
Fluss supports Apache Flink's Table API and Flnk's DataStream API.
3636

37+
For Flink's Table API, Fluss supports the following features:
3738

3839
| Feature support | Flink | Notes |
3940
|---------------------------------------------------|-------|----------------------------------------|
@@ -53,6 +54,8 @@ Fluss only supports Apache Flink's Table API.
5354
| [SQL update](writes.md#update) | ✔️ | Only in batch mode. |
5455
| [SQL lookup join](lookups.md) | ✔️ | |
5556

57+
For Flink's DataStream API, you can see [DataStream API](docs/engine-flink/datastream.mdx) for more details.
58+
5659
## Preparation when using Flink SQL Client
5760
- **Download Flink**
5861

‎website/docs/maintenance/operations/_category_.json‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"label": "Operations",
3+
"position": 5
4+
}

‎website/docs/maintenance/operations/racks.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
---
2+
title: Racks
3+
sidebar_position: 2
4+
---
5+
6+
<!--
7+
Licensed to the Apache Software Foundation (ASF) under one
8+
or more contributor license agreements. See the NOTICE file
9+
distributed with this work for additional information
10+
regarding copyright ownership. The ASF licenses this file
11+
to you under the Apache License, Version 2.0 (the
12+
"License"); you may not use this file except in compliance
13+
with the License. You may obtain a copy of the License at
14+
15+
http://www.apache.org/licenses/LICENSE-2.0
16+
17+
Unless required by applicable law or agreed to in writing, software
18+
distributed under the License is distributed on an "AS IS" BASIS,
19+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
20+
See the License for the specific language governing permissions and
21+
limitations under the License.
22+
-->
23+
24+
# Balancing Replicas Across Racks
25+
26+
The rack awareness feature is designed to distribute replicas of the same bucket across multiple racks. This extends the
27+
data protection guarantees provided by Fluss beyond server failures to include rack failures, thereby significantly
28+
reducing the risk of data loss in the event that all TabletServers on a single rack fail simultaneously.
29+
30+
To specify that a TabletServer belongs to a particular rack, you can set the `tablet-server.rack` configuration option:
31+
32+
```yaml title="conf/server.yaml"
33+
tablet-server.rack: RACK1
34+
```
35+
36+
:::note
37+
1. If rack awareness is enabled, the `tablet-server.rack` setting must be configured for each TabletServer. Failure to do so will prevent Fluss from starting and will result in an exception being thrown.
38+
:::
39+
40+
When a table is created, the rack constraint is honored, ensuring that replicas are spread across as many racks as possible.
41+
Specifically, a bucket will span the minimum of the number of available racks and the `table.replication.factor` (i.e., `min(#racks, table.replication.factor)`).
42+
This approach maximizes the distribution of replicas across racks.
43+
44+
The algorithm used to assign replicas to TabletServers ensures that the number of leader replicas per TabletServer
45+
remains consistent, regardless of how TabletServers are distributed across racks. This helps maintain balanced throughput
46+
across the system.
47+
48+
However, if racks are assigned different numbers of TabletServers, the distribution of replicas will not be even. Racks
49+
with fewer TabletServers will receive more replicas, leading to higher storage usage and increased resource allocation
50+
for replication. Therefore, it is highly recommended to configure an equal number of TabletServers per rack to ensure
51+
optimal resource utilization and balanced workload distribution.

‎website/docs/maintenance/operations/upgrading.md‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
---
2+
title: Upgrading and Compatibility
3+
sidebar_position: 1
4+
---
5+
6+
<!--
7+
Licensed to the Apache Software Foundation (ASF) under one
8+
or more contributor license agreements. See the NOTICE file
9+
distributed with this work for additional information
10+
regarding copyright ownership. The ASF licenses this file
11+
to you under the Apache License, Version 2.0 (the
12+
"License"); you may not use this file except in compliance
13+
with the License. You may obtain a copy of the License at
14+
15+
http://www.apache.org/licenses/LICENSE-2.0
16+
17+
Unless required by applicable law or agreed to in writing, software
18+
distributed under the License is distributed on an "AS IS" BASIS,
19+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
20+
See the License for the specific language governing permissions and
21+
limitations under the License.
22+
-->
23+
24+
As an online storage service, Fluss is typically designed to operate over extended periods, often spanning several years.
25+
Like all long-running services, Fluss requires ongoing maintenance, which includes fixing bugs, implementing improvements,
26+
and migrating applications to newer versions of the Fluss cluster. In our code design process, we place a strong emphasis
27+
on compatibility to ensure that any updates or changes are seamlessly integrated without disrupting the existing
28+
functionality or stability of the system.
29+
30+
This document provides detailed instructions on how to upgrade the Fluss server, as well as information on the
31+
compatibility between different versions of the Fluss client and the Fluss server.
32+
33+
## Upgrading the Fluss Server Version
34+
35+
This section outlines the general process for upgrading Fluss across versions. For server upgrades, we recommend using
36+
the rolling upgrade method. Specifically, upgrade the `TabletServers` one-by-one first, and then upgrade the `CoordinatorServer`.
37+
38+
:::note
39+
1. During the server upgrade process, read and write operations in the cluster will not be affected.
40+
2. Currently, the Fluss `CoordinatorServer` does not yet support high availability (HA). During the `CoordinatorServer` upgrade stage, the `CoordinatorServer` will be in an unavailable state, which will affect admin operations such as table creation.
41+
:::
42+
43+
The following is an example of upgrading the Fluss server from 0.6 to $FLUSS_VERSION$ on
44+
a [Distributed Cluster](docs/install-deploy/deploying-distributed-cluster.md):
45+
46+
### Download And Configure Fluss
47+
48+
1. First, download Fluss binary file for $FLUSS_VERSION$:
49+
50+
```shell
51+
tar -xzf fluss-$FLUSS_VERSION$-bin.tgz
52+
cd fluss-$FLUSS_VERSION$/
53+
```
54+
55+
2. If you want to enable [Lakehouse Storage](docs/maintenance/tiered-storage/lakehouse-storage.md), you need to prepare the required JAR files for the datalake first. For more details,
56+
see [Add other jars required by datalake](docs/maintenance/tiered-storage/lakehouse-storage.md#add-other-jars-required-by-datalake).
57+
58+
3. Next, copy the configuration options from 0.6 (`fluss-0.6/conf/server.yaml`) to the new configuration
59+
file (`fluss-$FLUSS_VERSION$/conf/server.yaml`). Adding any new options introduced in version $FLUSS_VERSION$ as
60+
needed to experience the new features.
61+
62+
### Upgrade the TabletServers one-by-one
63+
64+
To upgrade the `TabletServers`, follow these steps one-by-one for each `TabletServer`:
65+
66+
**Stop a TabletServer**
67+
68+
```shell
69+
./fluss-0.6/bin/tablet-server.sh stop
70+
```
71+
72+
**Restart the new TabletServer**
73+
74+
```shell
75+
./fluss-$FLUSS_VERSION$/bin/tablet-server.sh start
76+
```
77+
78+
### Upgrade the CoordinatorServer
79+
80+
After all `TabletServers` have been upgraded, you can proceed to upgrade the `CoordinatorServer` by following these steps:
81+
82+
**Stop the CoordinatorServer**
83+
84+
```shell
85+
./fluss-0.6/bin/coordinator-server.sh stop
86+
```
87+
88+
**Restart the new CoordinatorServer**
89+
90+
```shell
91+
./fluss-$FLUSS_VERSION$/bin/coordinator-server.sh start
92+
```
93+
94+
Once this process is complete, the server upgrade will be finished.
95+
96+
## Compatibility between Fluss Client and Fluss Server
97+
98+
The compatibility between the Fluss client and the Fluss server is described in the following table:
99+
100+
101+
| | Server 0.6 | Server 0.7 | Limitations |
102+
|------------|------------|------------|-------------|
103+
| Client 0.6 | ✔️ | ✔️ | |
104+
| Client 0.7 | ✔️ | ✔️ | |

0 commit comments

Comments
 (0)