Skip to content

Commit

Permalink
Remove Leader leases from v24.3 docs
Browse files Browse the repository at this point in the history
Fixes DOC-12000

They will be in Preview in v25.1
  • Loading branch information
Richard Loveland authored and Richard Loveland committed Dec 19, 2024
1 parent bf70b27 commit 5b7bdd7
Show file tree
Hide file tree
Showing 4 changed files with 1 addition and 35 deletions.
1 change: 0 additions & 1 deletion src/current/_includes/v24.3/leader-leases-intro.md

This file was deleted.

27 changes: 0 additions & 27 deletions src/current/v24.3/architecture/replication-layer.md
Original file line number Diff line number Diff line change
Expand Up @@ -148,33 +148,6 @@ A table's meta and system ranges (detailed in the [distribution layer]({% link {

However, unlike table data, system ranges cannot use epoch-based leases because that would create a circular dependency: system ranges are already being used to implement epoch-based leases for table data. Therefore, system ranges use expiration-based leases instead. Expiration-based leases expire at a particular timestamp (typically after a few seconds). However, as long as a node continues proposing Raft commands, it continues to extend the expiration of its leases. If it doesn't, the next node containing a replica of the range that tries to read from or write to the range will become the leaseholder.

#### Leader leases

{% include_cached new-in.html version="v24.3" %}

{% include feature-phases/preview.md %}

{% include {{ page.version.version }}/leader-leases-intro.md %}

Leader leases rely on a shared, store-wide failure detection mechanism for triggering new Raft elections. [Stores]({% link {{ page.version.version }}/cockroach-start.md %}#store) participate in Raft leader elections by "fortifying" a candidate replica based on that replica's _store liveness_, as determined among a quorum of all the node's stores. A replica can **only** become the Raft leader if it is so fortified.

After the fortified Raft leader is chosen, it is then also established as the leaseholder. Support for the lease is provided as long as the Raft leader's store liveness remains supported by a quorum of stores in the Raft group. This provides the fortified Raft leader with a guarantee that it will not lose leadership until **after** it has lost store liveness support. This guarantee enables a number of improvements to the performance and resiliency of CockroachDB's Raft implementation that were prevented by the need to handle cases where Raft leadership and range leases were not colocated.

Importantly, since Leader leases rely on a quorum of stores in the Raft group, they remove the need for the single point of failure (SPOF) that was the [node liveness range]({% link {{ page.version.version }}/cluster-setup-troubleshooting.md %}#node-liveness-issues), As a result, Leader leases are not vulnerable to the scenario possible under the previous leasing regime where a leaseholder was [partitioned]({% link {{ page.version.version }}/cluster-setup-troubleshooting.md %}#network-partition) from its followers (including a follower that was the Raft leader) but still heartbeating the node liveness range. Before Leader leases, this scenario would result in an indefinite outage that lasted as long as the lease was held by the partitioned node.

Based on Cockroach Labs' internal testing, leader leases provide the following user-facing benefits:

- [Network partitions]({% link {{ page.version.version }}/cluster-setup-troubleshooting.md %}#network-partition) between a leaseholder and its followers heal in less than 20 seconds, since the leaseholder no longer needs to heartbeat a single node liveness range.
- Outages caused by liveness failures last less than 1 second, since liveness is now determined by a store-level detection mechanism, not a single node liveness range.
- Performance is equivalent (within less than 1%) to epoch-based leases on a 100 node cluster of 32 vCPU machines with 8 stores each.

To enable Leader leases for testing with your workload, use the [cluster setting]({% link {{ page.version.version }}/cluster-settings.md %}) `kv.raft.leader_fortification.fraction_enabled`, which controls the fraction of ranges for which the Raft leader fortification protocol is enabled. Leader fortification is needed for a range to use a Leader lease. It can be set to `0.0` to disable leader fortification and, by extension, Leader leases. It can be set to `1.0` to enable leader fortification for all ranges and, by extension, use Leader leases for all ranges that do not require expiration-based leases. It can be set to a value between `0.0` and `1.0` to gradually roll out Leader leases across the ranges in a cluster.

{% include_cached copy-clipboard.html %}
~~~ sql
SET CLUSTER SETTING kv.raft.leader_fortification.fraction_enabled = 1.0
~~~

#### How leases are transferred from a dead node

When the cluster needs to access a range on a leaseholder node that is dead, that range's lease must be transferred to a healthy node. This process is as follows:
Expand Down
6 changes: 0 additions & 6 deletions src/current/v24.3/cockroachdb-feature-availability.md
Original file line number Diff line number Diff line change
Expand Up @@ -277,12 +277,6 @@ Command | Description
[`cockroach demo`]({% link {{ page.version.version }}/cockroach-demo.md %}) | Start a temporary, in-memory CockroachDB cluster, and open an interactive SQL shell to it.
[`cockroach sqlfmt`]({% link {{ page.version.version }}/cockroach-sqlfmt.md %}) | Reformat SQL queries for enhanced clarity.

### Leader leases

{% include {{ page.version.version }}/leader-leases-intro.md %}

For more information, see [Architecture > Replication Layer > Leader leases]({% link {{ page.version.version }}/architecture/replication-layer.md %}#leader-leases).

## See Also

- [`SHOW {session variable}`]({% link {{ page.version.version }}/show-vars.md %})
Expand Down
2 changes: 1 addition & 1 deletion src/current/v25.1/architecture/replication-layer.md
Original file line number Diff line number Diff line change
Expand Up @@ -150,7 +150,7 @@ However, unlike table data, system ranges cannot use epoch-based leases because

#### Leader leases


{% include_cached new-in.html version="v25.1" %}

{% include feature-phases/preview.md %}

Expand Down

0 comments on commit 5b7bdd7

Please sign in to comment.