[docs] Document KV leader replica capacity control

[wuchong]

Search before asking

• I searched the existing issues and found no documentation issue covering this feature.

Motivation

PR #3614 introduced resource-based KV leader replica capacity control to protect TabletServers from creating too many KV leader replicas. The feature is disabled by default and needs user-facing documentation explaining when and how to enable, disable, and configure it.

This was identified in the PR review discussion: #3614 (comment)

Documentation scope

Add documentation that covers:

• The purpose and behavior of KV leader replica capacity control.
• When operators should enable the feature and when leaving it disabled may be appropriate.
• How to enable and disable the feature with kv.leader-replica.memory-reserved:
  • 0 disables memory-based capacity control.
  • A positive value enables capacity estimation.
• How TabletServer resource capacity is detected and how it can be overridden with:
  • tablet-server.advertised-resource.cpu-cores
  • tablet-server.advertised-resource.memory-size
• Clarification that advertised resource options report capacity to the CoordinatorServer and do not enforce CPU, memory, cgroup, or JVM limits.
• The capacity calculation behavior:
  • The limit is applied only when more than half of live TabletServers report memory.
  • Unknown-memory TabletServers use the average memory of known TabletServers.
• Example configuration for enabling, tuning, and disabling the feature.
• Relevant metrics and the error users see when KV leader replica capacity is insufficient.

References

• Original feature issue: [server] Add resource-based KV leader replica capacity control #3613
• Implementation PR: [server] Add resource-based KV leader replica capacity control #3614
• Review discussion: [server] Add resource-based KV leader replica capacity control #3614 (comment)

[MaheshS08]

@wuchong , I'd like to work on this. I'll add a new doc page under website/docs/maintenance/operations/ (alongside racks.md and rebalance.md) covering:

• Overview of what the feature protects against
• Enabling/disabling via kv.leader-replica.memory-reserved
• TabletServer resource reporting via tablet-server.advertised-resource.*
• How capacity is calculated (including the "more than half must report memory" rule)
• The error surfaced when capacity is exceeded
• Relevant metrics (kvLeaderReplicaCount, kvLeaderReplicaCapacity)

Will open a PR referencing this issue once ready.

[wuchong]

Thanks @MaheshS08 , I assigned it to you.

Since Fluss also provides data disk write protection, I suggest making this a general resource protection page:

• Path: website/docs/maintenance/operations/resource-protection.md
• Title: Resource Protection

The page should contain these two main sections:

## Data Disk Write Protection

## KV Leader Replica Capacity Protection

This keeps the current protection mechanisms together while leaving room for adding more resource protection features in the future.

[wuchong]

cc @swuferhong